Intel IXA SDK ACE Programming Framework - Department of ...

Intel ® IXA SDK ACE Programming 

Framework 

IXA SDK 2.0 Developer’s Guide 

August 2001 

Document Number: A71582-001

Revision History 

Revision Date Revision Description 

August 2001 3.3 SDK 2.0 release. 

Information in this document is provided in connection with Intel ® products. No license, express or implied, by estoppel or otherwise, to any intellectual 

property rights is granted by this document. Except as provided in Intel’s Terms and Conditions of Sale for such products, Intel assumes no liability 

whatsoever, and Intel disclaims any express or implied warranty, relating to sale and/or use of Intel products including liability or warranties relating to 

fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Intel products are not 

intended for use in medical, life saving, or life sustaining applications. 

Intel may make changes to specifications and product descriptions at any time, without notice. 

Designers must not rely on the absence or characteristics of any features or instructions marked “reserved” or “undefined.” Intel reserves these for 

future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. 

The product may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current 

characterized errata are available on request. 

Intel Corporation might have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not 

give any license to these patents. 

This document as well as the software and hardware described in it are furnished under license and may only be used or copied in accordance with 

the terms of the license. The information in this document is furnished for informational use only, is subject to change without notice, and should not be 

construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear 

in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document 

may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation. 

Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order. 

Copies of documents which have an ordering number and are referenced in this document, or other Intel literature may be obtained by calling 

1-800-548-4725 or by visiting Intel’s website at http://www.intel.com 

Copyright © Intel Corporation, 2001. All rights reserved. 

*Other names and brands may be claimed as the property of others. 

This product includes software developed by parties other than Intel. See the back page of this document for a list of copyrights and license 

agreements.

Contents 

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . ix 

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix 

In This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix 

Other Sources of Information . . . . . . . . . . . . . . . . . . . . . . . xi 

Typographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . xi 

Installation Path . . . . . . . . . . . . . . . . . . . . . . . . . . . xii 

Syntax Example . . . . . . . . . . . . . . . . . . . . . . . . . . . xii 

Contacting Intel . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii 

Web and Internet Sites . . . . . . . . . . . . . . . . . . . . . . . . xii 

Customer Support Technicians . . . . . . . . . . . . . . . . . . . . xiii 

Chapter 1 Introduction and Overview . . . . . . . . . . . . . . . . . . . . 1 

Network Service Applications . . . . . . . . . . . . . . . . . . . . . . . 1 

Packet Classification . . . . . . . . . . . . . . . . . . . . . . . . . . 2 

The IXA Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 

Logical Elements of an IXA Application . . . . . . . . . . . . . . . . . . . 3 

The Data Plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

The Control Plane . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

The Management Plane . . . . . . . . . . . . . . . . . . . . . . . . 4 

Dividing Tasks Among Code Modules . . . . . . . . . . . . . . . . . . 5 

The ACE Programming Framework for Packet Handling. . . . . . . . . . . . 5 

Packet Processing and ACEs . . . . . . . . . . . . . . . . . . . . . . 5 

Writing ACEs using C, NCL and IXA IDL. . . . . . . . . . . . . . . . . 6 

Predefined ACEs . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 

Accelerated ACEs . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 

Dividing Tasks Among ACE Types . . . . . . . . . . . . . . . . . . . 8 

Using Stack ACEs . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

OMS for Global Application Services . . . . . . . . . . . . . . . . . . . 10 

Creating ACEs . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 

Defining the Traffic Flow Path with Targets . . . . . . . . . . . . . . . 11 

Contents 

iii 

Revision 3.3, August 2001

Communication Among ACEs. . . . . . . . . . . . . . . . . . . . . 12 

MicroACE Resource Manager . . . . . . . . . . . . . . . . . . . . . 13 

Hardware Architecture: The IXP1200 Network Processor . . . . . . . . . . 14 

Software Configuration . . . . . . . . . . . . . . . . . . . . . . . . 14 

Hardware Configuration . . . . . . . . . . . . . . . . . . . . . . . 15 

Deploying Applications. . . . . . . . . . . . . . . . . . . . . . . . 17 

Components of the IXA SDK for the IXP1200 . . . . . . . . . . . . . . . . 17 

Chapter 2 Elements of an Application . . . . . . . . . . . . . . . . . . . . 19 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

The Object Management System . . . . . . . . . . . . . . . . . . . . . 20 

Parts of the OMS. . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

Accessing the OMS. . . . . . . . . . . . . . . . . . . . . . . . . . 21 

Naming Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

For More Information . . . . . . . . . . . . . . . . . . . . . . . . 21 

ACEs and Support Structures. . . . . . . . . . . . . . . . . . . . . . . 22 

Creating ACEs. . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Support Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

Additional Services . . . . . . . . . . . . . . . . . . . . . . . . . 23 

Supporting Languages . . . . . . . . . . . . . . . . . . . . . . . . 23 

Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

MicroACE Support Services . . . . . . . . . . . . . . . . . . . . . . . 24 

The Application Building Process . . . . . . . . . . . . . . . . . . . . . 25 

Chapter 3 Compiling and Testing Applications . . . . . . . . . . . . . . . 29 

Overview of the ACE Compilation and Linking Process . . . . . . . . . . . 29 

Intermediate Compilation . . . . . . . . . . . . . . . . . . . . . . . 29 

Compiling and Linking Source Files . . . . . . . . . . . . . . . . . . 30 

Compiling Kernel ACEs . . . . . . . . . . . . . . . . . . . . . . . 31 

Compiling MicroACEs. . . . . . . . . . . . . . . . . . . . . . . . . . 32 

Using Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Debugging an Application . . . . . . . . . . . . . . . . . . . . . . . . 33 

Chapter 4 Configuring and Starting IXA Systems . . . . . . . . . . . . . . 35 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

For Additional Information . . . . . . . . . . . . . . . . . . . . . . 36 

Using Startup Scripts and Configuration Files . . . . . . . . . . . . . . . 36 

Starting and Initializing Interface ACEs . . . . . . . . . . . . . . . . . 37 

Microengine Threads . . . . . . . . . . . . . . . . . . . . . . . . . 37 

The System Configuration File . . . . . . . . . . . . . . . . . . . . . . 37 

Configuring Network Interfaces . . . . . . . . . . . . . . . . . . . . 38 

Identifying Microcode Images . . . . . . . . . . . . . . . . . . . . . 38 

Starting and Configuring Aces . . . . . . . . . . . . . . . . . . . . . 38 

Setting Up Particular Configurations . . . . . . . . . . . . . . . . . . . 39 

Configuring an L2 Bridge . . . . . . . . . . . . . . . . . . . . . . . 40 

System Configuration File . . . . . . . . . . . . . . . . . . . . . 40 

iv 

Contents 


L2 Bridging Configuration File . . . . . . . . . . . . . . . . . . . 41 

Configuring an L3 Forwarder . . . . . . . . . . . . . . . . . . . . . 42 


L3 Forwarder Configuration File . . . . . . . . . . . . . . . . . . 43 

Configuring an L3 Forwarder with NAT . . . . . . . . . . . . . . . . 44 


NAT Configuration File . . . . . . . . . . . . . . . . . . . . . . 45 

Launching Application ACEs. . . . . . . . . . . . . . . . . . . . . . . 46 

Chapter 5 Controlling Packet Flow . . . . . . . . . . . . . . . . . . . . . . 47 

Defining Packet Flow . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

Physical Packet Flow . . . . . . . . . . . . . . . . . . . . . . . . . 48 

Logical Packet Flow . . . . . . . . . . . . . . . . . . . . . . . . . 48 

Binding Targets as Packet Destinations . . . . . . . . . . . . . . . . . . 48 

Binding Targets and ACEs . . . . . . . . . . . . . . . . . . . . . . 49 

Unbound Targets . . . . . . . . . . . . . . . . . . . . . . . . . . 50 

Defining Additional Targets . . . . . . . . . . . . . . . . . . . . . . . 50 

Directing Packets to a Target . . . . . . . . . . . . . . . . . . . . . . . 51 

Using Targets for Packet Processing . . . . . . . . . . . . . . . . . . . . 51 

Serial Packet Flow . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

Packet Flow Redirection . . . . . . . . . . . . . . . . . . . . . . . 52 

Receiving and Transmitting on Network Interface Ports . . . . . . . . . . . 53 

See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 

Chapter 6 Writing MicroACEs . . . . . . . . . . . . . . . . . . . . . . . . . 55 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

MicroACE Architectural Elements . . . . . . . . . . . . . . . . . . . . 56 

Architecture Summary . . . . . . . . . . . . . . . . . . . . . . . . 57 

Loading MicroACEs . . . . . . . . . . . . . . . . . . . . . . . . . . 58 

Setting Up a Processing Pipeline for MicroACEs . . . . . . . . . . . . . 59 

Creating Static Bindings . . . . . . . . . . . . . . . . . . . . . . 60 

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 

Writing the Core Component of a MicroACE . . . . . . . . . . . . . . . . 61 

Exception Packet Handling . . . . . . . . . . . . . . . . . . . . . . 62 

Initializing a MicroACE . . . . . . . . . . . . . . . . . . . . . . . 62 

Initialization Example . . . . . . . . . . . . . . . . . . . . . . . 63 

Terminating a MicroACE . . . . . . . . . . . . . . . . . . . . . . . 64 

Termination Example . . . . . . . . . . . . . . . . . . . . . . . 64 

Writing an Exception Packet Handler. . . . . . . . . . . . . . . . . . 64 

Exception Packet Handler Example . . . . . . . . . . . . . . . . . 65 

Allocating Memory for Shared Data . . . . . . . . . . . . . . . . . . 65 

Shared Memory Table Example . . . . . . . . . . . . . . . . . . . . 66 

Microcode Side: Hash Initialization and Table Implementation . . . . . 66 

Core Processor Side: Core Component Hashing. . . . . . . . . . . . 67 

Configuring MicroACEs with Crosscalls . . . . . . . . . . . . . . . . . . 68 

Microblock Types and Groups . . . . . . . . . . . . . . . . . . . . . . 68 

Microblock Types . . . . . . . . . . . . . . . . . . . . . . . . . . 69 

Contents 

v 


Source Microblocks . . . . . . . . . . . . . . . . . . . . . . . . 69 

Transform Microblocks . . . . . . . . . . . . . . . . . . . . . . 70 

Sink Microblocks . . . . . . . . . . . . . . . . . . . . . . . . . 70 

Examples of Microblocks . . . . . . . . . . . . . . . . . . . . . . . 70 

Writing a Dispatch Loop . . . . . . . . . . . . . . . . . . . . . . . . . 71 

Dispatch Loop Global Registers . . . . . . . . . . . . . . . . . . . . 72 

Defining Additional Global Registers . . . . . . . . . . . . . . . . 73 

Implementing Control Flow . . . . . . . . . . . . . . . . . . . . . . 73 

Dispatch Loop Example. . . . . . . . . . . . . . . . . . . . . . . . 73 

Writing a Microblock . . . . . . . . . . . . . . . . . . . . . . . . . . 75 

Returning Values to the Dispatch Loop . . . . . . . . . . . . . . . . . 75 

Transmitting a Packet . . . . . . . . . . . . . . . . . . . . . . . . 75 

Sending an Exception. . . . . . . . . . . . . . . . . . . . . . . . . 76 

MicroACE Design Example . . . . . . . . . . . . . . . . . . . . . . . 77 

Chapter 7 Interface ACEs . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 

Interface ACE Crosscalls . . . . . . . . . . . . . . . . . . . . . . . 80 

Source Code Location . . . . . . . . . . . . . . . . . . . . . . . . 81 

Initializing Interface ACEs . . . . . . . . . . . . . . . . . . . . . . . . 81 

Creating a Microcode Image with an Interface ACE Microblock . . . . . . 81 

Starting, Naming, and Binding Interface ACEs . . . . . . . . . . . . . . 82 

The Input ACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

Configuring Interface ACEs Using Crosscalls . . . . . . . . . . . . . . 83 

Responding to Input ACE Configuration Crosscalls . . . . . . . . . . . 84 

Managing Physical Ports . . . . . . . . . . . . . . . . . . . . . . . 84 

Managing Logical Port Configuration. . . . . . . . . . . . . . . . . . 85 

The Output ACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 

Sample Output Configurations . . . . . . . . . . . . . . . . . . . . 86 

Chapter 8 Stack and Library ACEs . . . . . . . . . . . . . . . . . . . . . . 87 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 

The Stack ACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 

Starting and Configuring the Stack ACE . . . . . . . . . . . . . . . . 88 

The L3 Forwarder Library ACE . . . . . . . . . . . . . . . . . . . . . . 89 

Starting the Forwarder ACE . . . . . . . . . . . . . . . . . . . . . . 90 

Binding the Targets . . . . . . . . . . . . . . . . . . . . . . . . . 90 

Configuring the Forwarder . . . . . . . . . . . . . . . . . . . . . . 90 

The L2 Bridging Library ACE. . . . . . . . . . . . . . . . . . . . . . . 91 

Packet Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 92 

Starting the L2 Bridger . . . . . . . . . . . . . . . . . . . . . . . . 93 

Configuring the L2 Bridger . . . . . . . . . . . . . . . . . . . . . . 94 

The NAT Library ACEs . . . . . . . . . . . . . . . . . . . . . . . . . 94 

Packet Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 94 

Special Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

FTP Packet Handling . . . . . . . . . . . . . . . . . . . . . . . 95 

TCP Fragment Handling . . . . . . . . . . . . . . . . . . . . . . 96 

vi 

Contents 


ICMP Error Packet Handling . . . . . . . . . . . . . . . . . . . . 96 

Starting the NAT ACEs . . . . . . . . . . . . . . . . . . . . . . . . 96 

Binding the Targets . . . . . . . . . . . . . . . . . . . . . . . . . 97 

Configuring the NAT library ACEs. . . . . . . . . . . . . . . . . . . 98 

Chapter 9 Classifying Packets Using NCL . . . . . . . . . . . . . . . . . . 99 

How ACEs Handle Packets . . . . . . . . . . . . . . . . . . . . . . . 99 

What’s in the NCL Rules File . . . . . . . . . . . . . . . . . . . . . . 100 

Classification Elements . . . . . . . . . . . . . . . . . . . . . . . . 100 

Sets and Searches . . . . . . . . . . . . . . . . . . . . . . . . . . 100 

Defining Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 

Defining Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 

How Rules Are Evaluated . . . . . . . . . . . . . . . . . . . . . . . . 103 

What Rules Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 

Chapter 10 Initializing and Acting on Packets in an ACE . . . . . . . . . 105 

ACE Code Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 105 

Initializing the ACE . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Defining ASL Objects. . . . . . . . . . . . . . . . . . . . . . . . . 106 

Defining the Initialization Function . . . . . . . . . . . . . . . . . . 107 

Defining Action and Utility Functions . . . . . . . . . . . . . . . . . . . 108 

Defining Action Functions . . . . . . . . . . . . . . . . . . . . . . 108 

Action Function Return Values . . . . . . . . . . . . . . . . . . . 108 

Predefined Default Action Function . . . . . . . . . . . . . . . . . 109 

For More Information . . . . . . . . . . . . . . . . . . . . . . . 109 

Defining Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . 109 

Defining Utility Functions . . . . . . . . . . . . . . . . . . . . . . 109 

What Action Functions Do . . . . . . . . . . . . . . . . . . . . . . . . 110 

Chapter 11 Communication Within an Application . . . . . . . . . . . . . 113 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 

Defining Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . 114 

Making and Receiving Remote Calls . . . . . . . . . . . . . . . . . . 114 

When to Use Crosscalls . . . . . . . . . . . . . . . . . . . . . . . . 115 

Defining Crosscall Interfaces . . . . . . . . . . . . . . . . . . . . . . . 116 

Generated Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

Organizing Call Operations . . . . . . . . . . . . . . . . . . . . . . 117 

Defining Call Operations . . . . . . . . . . . . . . . . . . . . . . . . 118 

Operation Names . . . . . . . . . . . . . . . . . . . . . . . . . . 119 

Invocation Types for Operations . . . . . . . . . . . . . . . . . . . . . 120 

One-way Operations . . . . . . . . . . . . . . . . . . . . . . . . . 120 

Two-way Operations . . . . . . . . . . . . . . . . . . . . . . . . . 120 

Deferred Operations . . . . . . . . . . . . . . . . . . . . . . . . . 121 

Handling Asynchronous Responses with a Callback Function . . . . . 121 

Specifying Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . 122 

Declaring Argument Directions . . . . . . . . . . . . . . . . . . . . 122 

Contents 

vii 


Integrating Crosscalls with Applications . . . . . . . . . . . . . . . . . . 123 

Threads and Crosscalls . . . . . . . . . . . . . . . . . . . . . . . . 124 

Crosscalls and Library ACEs . . . . . . . . . . . . . . . . . . . . . 124 

Initializing and Terminating Interfaces. . . . . . . . . . . . . . . . . . . 125 

Initializing the Client . . . . . . . . . . . . . . . . . . . . . . . . . 125 

Client Initialization Example . . . . . . . . . . . . . . . . . . . . . 125 

Initializing the Server. . . . . . . . . . . . . . . . . . . . . . . . . 128 

Server Initialization Example . . . . . . . . . . . . . . . . . . . . . 129 

Initializing Function Pointers . . . . . . . . . . . . . . . . . . . . . 130 

Invoking Crosscall Functions . . . . . . . . . . . . . . . . . . . . . . . 130 

Opening a Crosscall Connection . . . . . . . . . . . . . . . . . . . . 131 

Remote Call Example. . . . . . . . . . . . . . . . . . . . . . . . . 131 

Passing Crosscall Arguments . . . . . . . . . . . . . . . . . . . . . . . 133 

Client Side Parameter Passing . . . . . . . . . . . . . . . . . . . . . 134 

What the Stub Function Does to Passed Parameters . . . . . . . . . . 135 

Server Side Parameter Passing . . . . . . . . . . . . . . . . . . . . . 135 

Passing Values in a One-way Call . . . . . . . . . . . . . . . . . . . 136 

Passing Values in a Two-way Call . . . . . . . . . . . . . . . . . . . 136 

Passing Values in a Deferred Call . . . . . . . . . . . . . . . . . . . 137 

Chapter 12 Crosscall Example . . . . . . . . . . . . . . . . . . . . . . . . 139 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

Example Interface Definition . . . . . . . . . . . . . . . . . . . . . . . 140 

Generated Stub Files . . . . . . . . . . . . . . . . . . . . . . . . . 140 

Generated Skeleton Files . . . . . . . . . . . . . . . . . . . . . . . 143 

Writing the Crosscall Client . . . . . . . . . . . . . . . . . . . . . . . 144 

Writing the Crosscall Server . . . . . . . . . . . . . . . . . . . . . . . 152 

Terminating the Server . . . . . . . . . . . . . . . . . . . . . . . . 159 

Chapter 13 Using Sets of Data to Classify Packets . . . . . . . . . . . . . 161 

Overview of Sets and Searches . . . . . . . . . . . . . . . . . . . . . . 161 

When to Use Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 

Defining Sets and Searches . . . . . . . . . . . . . . . . . . . . . . . 162 

Defining Sets in NCL . . . . . . . . . . . . . . . . . . . . . . . . . 162 

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 


Defining Sets in ASL . . . . . . . . . . . . . . . . . . . . . . . . . 164 

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 

Initializing and Populating Sets . . . . . . . . . . . . . . . . . . . . . . 165 

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 


How to Use Sets and Searches . . . . . . . . . . . . . . . . . . . . . . 167 

Using Searches in Rules. . . . . . . . . . . . . . . . . . . . . . . . 167 

Using Actions to Modify Sets . . . . . . . . . . . . . . . . . . . . . 167 

Deleting Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 

viii 

Contents 


About This Guide 

This guide introduces you to the Intel ® Internet Exchange Architecture (IXA) software 

development kit (SDK). This software enables you to develop and deliver 

networking applications that define rules to classify network packet traffic, and take 

actions based on these rules to manage the network traffic. 

To develop these networking applications, you need the following: 

l The IXA SDK, a full set of tools for developing applications and run-time libraries 

for delivering applications 

l 

A board or system containing the Intel IXP1200 network processor, a high-speed 

packet-processing chip, such as the IXDP1200 Advanced Development Platform. 

This guide helps you get started creating and testing networking applications for 

IXP1200s using the IXA SDK. 

Audience 

This guide is intended for software developers who will design, develop, and deliver 

network applications that must process packets at high speed. It assumes that you are 

familiar with the following: 

l 

l 

l 

C programming 

The Linux * and GNU development environment and toolset 

Realtime network applications 

In This Guide 

This guide includes the following chapters: 

l 

Chapter 1, “Introduction and Overview,” which gives an overview of the IXA 

application architecture and system software 


ix 


In This Guide 

l 

l 

l 

l 

l 

l 

l 

l 

l 

l 

l 

l 

Chapter 2, “Elements of an Application,” which introduces the IXA system software, 

the C structures that support the ACE model, the error handling system, 

and the application building process 

Chapter 3, “Compiling and Testing Applications,” which explains the compilation 

model for an application containing ACEs 

Chapter 4, “Configuring and Starting IXA Systems,” which explains how to 

configure the ports and start the ACEs for an IXA system 

Chapter 5, “Controlling Packet Flow,” which introduces targets as destinations 

for packets and explains how packets flow into and out of an IXP1200 and ACEs 

within an application 

Chapter 6, “Writing MicroACEs,” which explains the architecture of microACEs 

and describes how to write them 

Chapter 7, “Interface ACEs,” which introduces the system-defined microACEs 

that receive and transmit packets on network interface ports 

Chapter 8, “Stack and Library ACEs,” which introduces the system-defined 

microACE that represents the Linux TCP/IP stack and library ACEs that perform 

common networking tasks 

Chapter 9, “Classifying Packets Using NCL,” which introduces the Network 

Classification Language and explains how to use it to evaluate packets and write 

classification rules 

Chapter 10, “Initializing and Acting on Packets in an ACE,” which describes 

some of the actions that you can take on packets and explains how to implement 

action functions 

Chapter 11, “Communication Within an Application,” which shows how to use 

the crosscall mechanism for remote function calls between ACEs and other 

programs 

Chapter 12, “Crosscall Example,” which demonstrates the use of crosscalls 

Chapter 13, “Using Sets of Data to Classify Packets,” which describes how to 

create sets to associate application data with packets, and how to perform and act 

on the results of searches in the sets 

x 



Other Sources of Information 

Other Sources of Information 

This guide is part of the Intel IXA SDK documentation set, which also includes: 

l 

l 

l 

l 

l 

l 

l 

Intel IXA SDK ACE Programming Framework Reference (IXA SDK Reference), which 

describes the Intel IXA SDK (software development kit), including the IXA API, 

which consists of the OMS services library, the action services library (ASL), and 

the microACE Resource Manager; the Network Classification Language (NCL); 

the IXA IDL interface definition language; and development tools 

Intel IXA SDK ACE Programming Framework Developer’s Guide (IXA SDK Developer’s 

Guide), which provides programmers with conceptual descriptions and 

instructions on writing networking applications for the IXP1200 using the IXA 

SDK 

Intel IXA SDK ACE Programming Framework Tutorial (IXA SDK Tutorial), which 

provides a step-by-step introduction to building a basic IXA application 

Intel IXA SDK ACE Programming Framework Release Notes (IXA SDK Release Notes), 

which lists information about the latest software release 

Intel IXA SDK for the IXP1200 Installation and Setup Guide (IXA SDK Installation and 

Setup Guide), which describes how to install the IXA SDK and set up the development 

environment 

Getting Started, which provides a high-level introduction to the product family 

and describes supported hardware and software configurations 

The IXP1200 Microengine Development Environment documentation set, which 

includes the following documents: 

— IXP1200 Network Processor Family Microcode Programmer’s Reference Manual 

— IXP1200 Network Processor Family Microcode Developer Tools User’s Guide 

— IXP1200 Network Processor Family Microcode Example Software 

— IXP1200 Network Processor Family Hardware Reference Manual 

— IXP1200 Macro Library Reference Manual 

— IXP1200 Macro Library Style Guide 

— IXDP1200 I/O Option Card Design Guide 

— Microengine C Compiler Language Support Reference Manual 

— Microengine C Compiler LIBC Reference Manual 

In addition, the Intel Web site provides valuable information on products, support, 

and the company. See “Contacting Intel” on page xii. 

Typographic Conventions 

This document uses the following typographic conventions to help you locate and 

identify information: 

Italic text 

Bold text 

Used for new terms, emphasis, and book titles; also identifies arguments 

in syntax descriptions. 

Identifies keywords and punctuation in syntax descriptions. 


xi 


Contacting Intel 

Courier font Identifies file names, folder names, and text that either appears on 

the screen or that you are required to type. 

NOTE: Provides extra information, tips, and hints regarding the topic. 

CAUTION: Identifies important information about actions that could result in 

damage to or loss of data or could cause the application to behave 

in unexpected ways. 

WARNING! 

Identifies critical information about actions that could result in 

equipment failure or bodily injury. 

Installation 

Path 

The pathname of the installation directory for the product is indicated by the 

following argument: 

SDKinstallpath 

The environment variable $IXROOT is set to the actual installation path during installation; 

you can use this variable if it is set in your environment. 

l 

l 

The default installation path for a Linux development system is /opt/ixasdk. 

The default installation path for a Windows NT * development system is 

C:\eLinuxIDE-IXP1200\cygwin\opt\ixasdk. 

Syntax 

Example 

Courier font is used for code. In syntax descriptions, bold indicates required 

keywords and a punctuation. In examples, bold highlights interesting parts. Italics 

indicate values that are to be replaced, such as arguments or file names. The 

following figure shows a sample of syntax notation. 

Keywords, required punctuation 

predicate predicate_name { boolean_expression } 

Arguments 


You can reach Intel’s automated support services 24 hours a day, every day at no 

charge. The services contain the most up-to-date information about Intel products. 

You can access installation instructions, troubleshooting information, and general 

product information. 

Web and 

Internet Sites 

You can use the Internet to download software updates, troubleshooting tips, installation 

notes, and more. 

l 

General online support services are on the World Wide Web at: 

xii 




http://support.intel.com 

l 

Online support services for the IXP1200 network processor are at: 

http://support.intel.com/support/network/processor/ixp1200/ 

For specific types of information and services, go to the following Web and Internet 

sites: 

l 

l 

l 

l 

l 

l 

l 

Corporate: http://www.intel.com 

Networking products: http://www.intel.com/network/ 

Intel IXA information: http://developer.intel.com/design/ixa/ 

IXA SDK: http://www.intel.com/design/network/products/software/index.htm 

IXP1200 developer site: 

http://developer.intel.com/design/network/products/npfamily/ixp1200.htm 

FTP host: download.intel.com 

FTP directory: /support/network/adapter 

Customer 

Support 

Technicians 

l 

l 

United States and Canada: 1.916.377.7000 (7:00 - 17:00 M-F Pacific Time) 

Worldwide access: Intel has technical support centers worldwide. Many of the 

centers are staffed by technicians who speak the local languages. For a list of all 

Intel support centers, their telephone numbers, and the times they are open, go to: 

http://support.intel.com/support/9089.htm 


xiii 



xiv 



Chapter 1 

Introduction and Overview 

This chapter introduces you to the tools that Intel ® provides to develop and deliver 

network service applications using Intel’s Internet Exchange Architecture for 

theIXP1200 network processor. 

This chapter contains the following topics: 

l “Network Service Applications” on page 1 

l “Logical Elements of an IXA Application” on page 3 

l “The ACE Programming Framework for Packet Handling” on page 5 

l “OMS for Global Application Services” on page 10 

l “Hardware Architecture: The IXP1200 Network Processor” on page 14 

l “Components of the IXA SDK for the IXP1200” on page 17 

Network Service Applications 

Networks have become a core component of businesses; their operation is critical to 

the businesses’ daily operation. Applications have become increasingly complex in 

order to manage, secure, and optimize these networks. 

Application developers and equipment manufacturers must develop and enhance 

these applications to meet the rapidly changing needs of their users while ensuring 

that networks operate with optimal performance. 

The following are common examples of network services applications: 

l Firewalls 

l Virtual private networks (VPN) 

l Intrusion detection systems 

l RMON statistical monitoring applications 

Revision 3.3, August 2001 

Introduction and Overview 1

Network Service Applications 

l 

l 

l 

l 

l 

Load-balancing systems 

Quality of service (QoS) applications 

Voice over IP (VOIP) applications 

Protocol conversion 

Layer 3 forwarding 

Packet 

Classification 

At the highest level, as shown in the following figure, a network services application 

consists of the following: 

l 

l 

Interfaces to and from one or more networks (called network interface ports) 

Applications that process packets traveling on the networks 

Packet flow 

Input interface 

Application 

Output interface 

Such an application classifies the packets—that is, it compares the packet contents 

against some set of selection criteria. It then takes some action determined by the 

result of the classification and disposes of the packets. For example, it might: 

l 

l 

l 

View packets and simply decide whether to pass them to another interface or 

application, or to drop them 

Collect information about the packets and report on the flow of data 

Manipulate the packets in some way 

The following figure shows how packets might flow through a forwarding application. 

Packet flow 


Packet classification and action 

Yes 

In data table? 

No 

Good packet? 

No 

Drop 


Yes; update data 

The IXA 

Solution 

The Intel Internet Exchange Architecture provides an efficient and flexible hardware 

and software infrastructure for developing and delivering network services applications. 

You can develop applications for this architecture using the application 

programming interface (API), the IXA API. 

2 Introduction and Overview 


Logical Elements of an IXA Application 

Applications that you develop with the IXA API are known as IXA applications. The 

IXA software development kit (SDK) provides tools and libraries that allow you to 

quickly and easily develop and deliver IXA applications. These applications directly 

manipulate packets, independent of the protocol layer. 

You use the IXA SDK to produce applications for a hardware configuration that 

includes one or more IXP1200 network processors. Both the software and hardware 

are optimized for maximum efficiency in providing network services. 

The rest of this document describes: 

l 

l 

l 

The logical architecture and major software elements of an IXA application 

The IXP1200 network processor, and how you develop and deploy your application 

software in the hardware environment 

The tools and libraries provided by the IXA SDK 


To understand the IXA software architecture, you must understand the basic levels 

of tasks that a network services application performs. A network services application 

typically operates on three logical planes: 

l 

l 

l 

The data processing plane 

Data plane functions include the handling and forwarding of incoming packets at 

high speed. 

The control plane 

Control functions include the handling of exceptional cases or errors, and the 

creation and maintenance of both application objects and the tables or data sets 

that the data processing part uses for lookups. 

The management plane 

The manager for an application creates and initializes the objects in the other 

parts, and starts their execution. High-level management can include, for 

example, system or object configuration, or stopping and starting application 

functions in response to environmental conditions or user input. A manager 

might handle alerts, status reports, and other messages that the application generates. 

The Data Plane 

A part of an IXA application that performs data plane functions is a data processor 

(sometimes called a forwarding element). It receives buffers of data (containing cells, 

packets, frames, or even generalized I/O buffers) from a network interface, classifies 

them according to their protocols or contents, and determines their disposition by 

performing lookups in data tables. The data processor handles the fast path—the most 

frequent and usual operations—such as packet forwarding. This part of an application 

is optimized for performance and handles the bulk of network traffic. 

For the IXP1200, data processors are commonly implemented as microACEs compiled 

specifically for the microengines. (See “Accelerated ACEs” on page 7.) 

Introduction and Overview 3 



The Control 

Plane 

A part of an IXA application that performs control plane functions is a controller 

(sometimes called a control element). This part performs complex or time-consuming 

tasks that are encountered in the course of packet processing. 

For example, when a data processor for a routing application encounters a packet for 

which there is no entry in the routing table, it can send that packet to the controller. 

This leaves the data processor free to continue forwarding traffic while the controller 

finds the proper route and adds it to the table, or otherwise handles the exception. 

For the IXP1200, controllers are commonly implemented as conventional ACEs and 

compiled for the core processor, which provides more operating system services. 

Another alternative is to implement controllers using third-party protocol stack software 

modified for use with the IXA SDK. 

The 

Management 

Plane 

A part of an IXA application that performs management functions is a manager 

program. Management tasks can be handled by an off-chip application or by a standard 

Linux * application that runs on the IXP1200. The management code for the IXA 

application is commonly part of a larger application that includes some sort of user 

interface. This part can communicate with the control and data processing pieces by 

making calls to the IXP1200 system software. 

The manager program might, for example, get information from a user through a 

graphical user interface (GUI) and respond by changing the direction of packet flow 

between parts of the IXA application. Similarly, it might respond to an error message 

from the controller by displaying a message to a user through a GUI. 

In embedded systems, a manager program might implement an application-specific 

management protocol between an IXP1200 subsystem and a central management 

element; for example, communication between an IXP1200-based line card and a 

management card over a chassis backplane. 

Data/control flow 

Layer 3 Stateful Load 

routing firewall balancer 

application application application 

Management 

application 

Management 

plane 

Route 

management, 

UI 

Policy 

management, 

GUI 

Policy 

management, 

GUI 

Control 

module 

Control 

plane 

OSPF, 

RIP2, ... 

Connection 

setup 

Connection 

setup, 

resource 

allocation 

Data 

processing 

module 

Data 

plane 

Packet 

forward 

Packet 

pass, drop, 

NAT, ... 

Packet 

forward, 

NAT 

Traffic flow 



The ACE Programming Framework for Packet Handling 

Dividing Tasks 

Among Code 

Modules 

You can divide the tasks belonging to each functional plane among code modules in 

any number of ways, depending on the complexity of your application. A single 

control module, for example, might receive messages from multiple data processing 

modules, or you might create separate control modules for different control tasks. 

Similarly, you might combine control and management plane tasks into a single code 

module, or keep them separate. 

Different code modules can be compiled to run on different processors, depending on 

what is available and appropriate to a module’s tasks. 

l 

l 

Data processing and control modules are commonly located on an IXP1200 

network processor where they can react to and process packets at high speeds. 

They can be further optimized by compiling them specifically for different processors 

on the IXP1200 network processor. 

A manager program might be located on another processor where it has access to 

user interfaces, storage, and the full range of services provided by the operating 

system. 

For more information on hardware platforms and deployment options, see “Hardware 

Architecture: The IXP1200 Network Processor” on page 14. 


In order to encapsulate and modularize the unique tasks involved in packet 

processing, the IXA API defines a software construct called an active computing 

element (ACE). ACEs are represented by a C structure, ix_ace. 

Packet 

Processing 

and ACEs 

ACEs are the primary software components for processing packets. Both the data 

processing and control parts of an application contain ACEs. ACEs classify the 

packets, act on them according to these classifications, and determine their disposition. 

You organize ACEs as a serial processing pipeline, with packets passed from one 

ACE to another. Each one can inspect, classify, manipulate, and forward the packets 

that it receives. 

Packet processing takes place as a sequence of steps. Each step is performed by a 

separate ACE, and consists of a classification phase and an action phase. 

— During the classification phase, the ACE evaluates rules to determine if 

specific conditions or criteria exist. If a rule is true, the ACE places an associated 

action on a queue to be performed after all rules have been evaluated. 

More than one rule can be true, in which case all associated actions are queued. 

— During the action phase, the ACE executes all scheduled actions. If no rules 

are true, the ACE takes a default action, such as delivering the packet to a 

default destination or discarding it. ACEs can modify, drop, duplicate, or 

simply inspect the packets that they receive. Thus, packets can appear, disappear, 

or be changed as they flow through the ACEs. 




An ACE is defined by several distinct source code files. An initialization part, which 

creates and initializes needed structures and variables, and the action part, which 

defines the associated action functions, are written in C/C++. The classification part of 

the ACE, which defines a set of packet classification rules, is written in Network Classification 

Language (NCL ) 

Each ACE generally performs one type of packet handling or data control task. You 

can distribute tasks among ACEs, and ACEs among code modules in any way that is 

logical for your application. The following figure shows the high-level architecture of 

a typical IXA application. 

Managing application 

Object creation, 

flow control 

Error handling, status 

ACE 

Control module 


Data 

management 

Data initialization, 

configuration 

Exception cases 



Packet flow 



Data processing modules 

You can create your own ACEs using the IXA API, or you can use predefined ACEs 

that perform specific network processing tasks, as described below in “Predefined 

ACEs.” 

Your application defines the flow of packets among ACEs by creating packet destinations 

called targets and by binding the targets to other ACEs; see “Defining the Traffic 

Flow Path with Targets” on page 11. 

Writing ACEs 

using C, NCL 

and IXA IDL 

In the initialization part of an ACE, you create the ACE structure itself, with its 

related communication methods and data structures, using the ASL core C library. 

In the classification part of an ACE, rules can compare packet contents against static 

values or against dynamic data. You define these rules using the Network Classification 

Language (NCL) provided with the IXA SDK. NCL is a domain-specific objectoriented 

language for defining packet classification rules and identifying the associated 

actions to be taken when matches occur. This language-based approach makes 

it easy for you to specify the required classification criteria. 




In the action part of an ACE, you define the ACE infrastructure and action functions 

in C/C++. In the action functions, you can use run-time support for networking tasks 

provided by the ASL application services. These C/C++ class and function libraries 

provide support for handling application-specific operations; for example, TCP/IP 

operations such as IP fragmentation and reassembly, Network Address Translation 

(NAT), and TCP connection monitoring and stream reconstruction. 

For communication between ACEs and other parts of an application, you define 

remote function calls, using an interface definition language, IXA IDL. This compiles 

to C and becomes part of the ACE’s C source code. See “Communication Among 

ACEs” on page 12. 

Predefined 

ACEs 

Depending on who develops it and how it is created, an ACE can be a user ACE, a 

library ACE, or a system ACE. You can combine all three types in an application. 

l 

l 

User ACEs 

User ACEs are those that you develop yourself, defining all of the classification 

rules and actions. 

Library ACEs 

Intel supplies a set of predefined library ACEs, which provide building blocks for 

common application functionality such as layer 2 bridging and layer 3 (IP) 

forwarding. 

NOTE: 

Some library ACEs are supplied with source code so that you can configure 

them and modify their packet classification criteria and actions. When you 

modify a library ACE, it becomes a user ACE and is no longer supported and 

maintained by Intel. 

l 

System ACEs 

These platform-specific ACEs represent hardware network interfaces (interface 

ACEs) or protocol stacks (stack ACEs). The system ACEs are not necessarily implemented 

like other ACEs; they simply mask hardware and system details that are 

specific to a particular environment, and look like ACEs to your application. 

The system ACEs act as packet sources and destinations. They are opaque to other 

ACEs. You can configure system ACEs and communicate with them, but you 

cannot modify them. 

You customize the system initialization scripts to load and start the system ACEs 

your application and hardware configuration requires. The IXA SDK supplies 

system ACEs for the Ethernet * 10/100 and gigabit ports on the IXDP1200 

Advanced Development Platform, and for the Linux TCP/IP stack. 

Accelerated 


The ACE architecture allows an ACE to take advantage of the speed of dedicated 

processors. An ACE that runs entirely on the core processor is a conventional ACE. An 

ACE that includes code for another processor is called an accelerated ACE. 

The IXA SDK provides a type of accelerated ACE called a microACE. The microACE 

programming model provides a framework for creating a packet-processing application 

that makes use of the IXP1200’s microengines. A microACE has two logical 

components, running on different processors: 




l 

l 

The core component of a microACE is a complete conventional ACE, with 

C/C++, NCL, and IXA IDL code. The core component runs on the core processor 

in the IXP1200. 

The acceleration component of a microACE, called a microblock, is hardwarespecific 

and is written in IXP1200 microcode (machine code). The microblock runs 

on the microengines in the IXP1200. It performs fast-path processing, but can 

exchange packets with its core component on the core processor to handle exception 

cases. 

For more information on hardware platforms and deployment options, see “Hardware 

Architecture: The IXP1200 Network Processor” on page 14. 

You use microACEs for optimized, high-speed (fast-path) processing. Because the 

IXP1200 network processor contains a number of microengines running in parallel, 

each with multiple threads, microACEs provide extremely high efficiency in basic 

packet handling. Most system ACEs and library ACEs are implemented as micro- 

ACEs. 

The IXA SDK includes a complete set of tools, including compilers, linkers, and 

debuggers, for working with microcode to develop microACEs. For more information 

on the architecture of microACEs, see Chapter 6, “Writing MicroACEs.” 

Dividing Tasks 

Among ACE 

Types 

Generally, a microACE looks in a packet to classify it, performs simple transformations 

(such as NAT or protocol conversion), and routes it to the appropriate target. 

Exceptions are reported to another (conventional) ACE for handling. This allows 

time-consuming operations to run in parallel without slowing down traffic. 

The following figure shows an example of a forwarding application that uses a 

microACE for data processing and a conventional ACE for control. 




Control plane 

FwdControl ACE 

Update cache & forward 

Full lookup 

Forwarding table 

Route entry 

prefix = 192.0.0.0 

ifnum = 82 

nexthop = 192.168.0.02 

Packet flow 


Data plane 

Forwarding cache 

Exception: 

Quick lookup 

not in cache 

Forwarder microACE 

Forward 

Fast path 


In this example, the application defines a data table with the forwarding information 

on the core processor, and keeps a smaller data cache in the microcode on the microengines. 

A microACE called Forwarder handles most packet forwarding. When it 

encounters a packet that does not have an entry in the local forwarding cache, it sends 

that packet to a conventional ACE, called FwdControl. While the FwdControl ACE 

does a full lookup in the complete forwarding table, the Forwarder ACE can 

continue to handle traffic flow. When FwdControl is finished, it updates the cache 

and, if appropriate, inserts the exception-case packet back into the traffic flow. 

l 

l 

The Resource Manager defines memory management functions for a small 

amount of memory that can be shared by the microengines and core processor. 

For more information, see the IXA SDK Reference. 

The IXA API defines data structures and functions for implementing larger data 

tables in unshared memory, called sets. For more information, see Chapter 13, 

“Using Sets of Data to Classify Packets.” 

Using Stack 


The IXA SDK allows you to tie the services of the Linux TCP/IP protocol stack into 

the structure of an IXA application. 

A system ACE called the stack ACE enables any other ACE in the system to deliver 

packets to—or receive packets from—the Linux kernel. You can then use standard 

sockets-based application software to implement portions of an IXA application 

without having to use the ACE software model. In this case, other ACEs in the system 



OMS for Global Application Services 

appear, from the Linux TCP/IP stack point of view, as standard Ethernet interfaces. 

This provides a means for you to re-use existing or third-party protocol stack or 

management plane software while migrating an application to the ACE model. 


Object Management System (OMS) services are part of the IXA API. The OMS, part of 

the IXA system software, is a single logical entity with components distributed 

throughout the system. Any ACE can make use of OMS services. Any program that 

must communicate with an ACE can do so by registering itself with the OMS as a task. 

An application uses global C functions defined by the OMS services to create, 

configure, control, and destroy objects and structures in all parts of the application, 

and to perform global tasks. The primary global services your application requires 

are: 

l 

l 

l 

Creating and destroying ACEs and tasks 

Defining and controlling packet flow using targets 

Communicating among ACEs and tasks 

The OMS contains the following parts: 

l The Resolver, which creates and deletes ACEs, and manages packet flow by 

binding ACEs and targets. 

l 

The Name Server, which manages the name space for the OMS, maintaining a 

correspondence between names and internal identifiers for ACEs, targets and 

tasks. The name space allows objects that might be distributed among processors 

to address one another unambiguously. 

In order to communicate with and through the OMS, a program must create a 

communications channel, a separate process or thread containing a communication 

access process, or CAP. A program can communicate with both the Resolver and the 

Name Server through the same CAP. When you create an ACE or task structure, a 

CAP is automatically created with it. The OMS provides functions to retrieve the 

CAP for use as an argument to other OMS functions. 

Creating ACEs 

An application’s manager program creates and initializes the application’s ACEs by 

calling Resolver functions in the OMS. To do this, it must first register with the OMS 

as a task, using the ASL function ix_task_init. The task provides access to a CAP 

channel through which to communicate with the Resolver. 

You define an initialization function in the ACE executable to create the ACE structure 

and all support structures such as packet destination targets, data sets and 

elements, crosscalls, and events. 

When the manager program creates the ACE, you pass the ACE executable to the 

Resolver function ix_res_create_ace. This calls the initialization function and 

starts the ACE’s main loop, which begins packet and crosscall event processing. 




The IXA SDK also supplies utilities to start and stop ACEs from the command line or 

from a script. 

Defining the 

Traffic Flow 

Path with 

Targets 

Packets flow from one ACE to another, with each ACE performing a specific operation. 

The packet flow starts with a system ACE that represents a network interface 

(see “Predefined ACEs” on page 7). You determine the order in which packets are 

directed from the system ACE through intermediate ACEs before they are directed 

back out to the network through a network interface, or dropped from traffic. 

An application defines the paths through which packets flow between ACEs by specifying 

a set of targets. A target is an object within an ACE that represents a destination 

for packets. Each ACE contains a set of targets to which it routes packets when it has 

finished processing them. Each action ends by directing a packet to a target. For 

example, here are three ACEs with targets; packet flow among ACEs is not yet implemented. 

Network interface ACE 

Target T1 

Packet flow ACE 1 

Decision? 

Target T2 

Target T3 

ACE 2 

Processing 

Target T4 

The application implements traffic flow between ACEs by binding targets in one ACE 

to other ACEs. When an application binds a target to an ACE, the target serves as the 

input queue for that ACE. The bound ACE is then downstream in the packet flow 

from the ACE containing the target. 

In the following diagram, target T1 is bound to ACE1; target T3 is bound to ACE2; 

and targets T2 and T4 have not yet been bound. 





Target T1 

Packet flow ACE 1 

Decision? 

Target T2 

Target T3 


Processing 

Target T4 

The management program for an application binds and unbinds targets and ACEs 

using Resolver functions (ix_res_bind and ix_res_unbind) that are part of the 

OMS services. The IXA SDK also supplies utilities to bind ACEs and targets from the 

command line or from a script. 

The target mechanism makes the actual identities of the ACEs transparent to the 

action code that forwards the packets. The management part of your application can 

change the bindings of targets to ACEs to alter the path of packet flow, without you 

having to change the code in the ACEs themselves. 

For more information, see Chapter 5, “Controlling Packet Flow.” 

Communicatio 

n Among ACEs 

ACEs often need to communicate with one another or with a managing application 

for various reasons. For example: 

l 

l 

l 

ACEs can send alerts or status reports to the managing application. 

ACEs in a data processor module can receive control messages and data from 

ACEs in a control module. 

ACEs can send occasional packet data to other ACEs for special processing, or can 

exchange messages among themselves to coordinate packet processing. 

Because ACEs and their managing application might be running on different platforms 

and be written in different languages, the OMS acts as a message broker, using 

a remote procedure call model for object communication. 

ACEs and tasks communicate using a crosscall interface for remote method invocation. 

Remote method calls are handled through the distributed OMS, which provides 

marshalling and format conversion to address differences in byte order and word 

size between different processors. 

An ACE or task can act as a server or a client for remote procedure calls. 

l 

l 

The call server contains a crosscall object with the call method implementation. 

The call client makes remote calls to the call server using a crosscall reference object. 




rules 

actions 

Remote 

procedure 

call 

CAP, crosscall reference 

OMS Communication Controller 

Client ACE 

Packet 

flow 

Packet 

classification 

CAP, crosscall 

Response 

(optional) 

Related 

actions 

Server ACE 

You define a crosscall interface for an application using an interface definition 

language, IXA IDL, that is provided with the IXA SDK. IXA IDL is not OMG IDL; it 

has been refined to specifically target the type of interfaces needed in network packet 

processing applications, rather than interfaces for general purpose applications. 

You define calls to be synchronous or asynchronous, with or without a response. The 

definition compiles to C code that implements the crosscall infrastructure, which you 

then modify to provide specific call functions. 

l 

l 

Modify the crosscall source file to implement application-specific call functions. 

Compile the source code into the call server executable. 

For asynchronous calls with response (deferred calls), modify the callback source 

file to implement the callback function that is executed when the call completes. 

Compile the source code for the crosscall references (stubs) and callbacks into the 

call client executable. 

Library ACEs and system ACEs typically export crosscall interfaces. ACEs defined in 

your application must import these interfaces and include the crosscall references in 

order to invoke the calls in the predefined ACEs. 

MicroACE 

Resource 

Manager 

Programs running on the core processor, including the core components of micro- 

ACEs and ACE management applications, communicate with the microengines 

using the microACE Resource Manager. The Resource Manager is system software 

that runs in the core processor kernel. The Resource Manager API allows a microACE 

management program to do the following: 

l 

l 

l 

l 

l 

Initialize and configure the IXP1200. 

Load code onto microengines. 

Enable and disable the microengines. 

Get and set the microengine configuration and resource assignments. 

Allocate and access uncached SRAM, SDRAM and scratch memory. 



Hardware Architecture: The IXP1200 Network Processor 

l 

l 

Create and bind microACEs. 

Send packets to and receive packets from the microengines. 

Details of the Resource Manager API are provided in the IXA SDK Reference. 


IXA applications run on the Intel IXP1200 network processor. The IXP1200 contains 

a StrongARM * core processor, a set of programmable microengines, onboard SDRAM 

and SRAM, and a high-speed bus. 

l 

l 

The StrongARM core processor is a general-purpose processor running an 

embedded Linux operating system. Conventional ACEs run on the core 

processor. 

The microengines are very high-speed processors that are specialized for packet 

processing. MicroACEs run in microengines. Because there are no OMS services 

in the microengines, a component runs on the core processor to handle communications 

and control functions for microACEs. 

The Intel IXDP1200 Advanced Development Platform incorporates the IXP1200 into 

a board that has sixteen Ethernet 10/100 ports and two gigabit ports. 

IXM1200 Network 

Processor Base Card 

Single-Board 

Computer 

IXP1200 

Network 

Processor 

StrongARM 

Microengines 

Software 

Configuration 

Your software environment includes the following: 

l 

l 

The IXP1200 embedded operating system is Linux. 

You must download the RAMdisk and Linux kernel onto the IXM1200 Network 

Processor Base Card. 

Your development environment is a combination of the Windows NT operating 

system and either a Linux platform or Cygwin for a Linux environment on the 

Windows NT platform, with the following development tools: 

— Microengine toolchain: Embedded Linux version of the IXP1200 Microengine 

Development Environment, running under Windows NT. 

This enables you to remotely develop and debug code running on 

Microengines on the IXP1200. You must install this from Volume II, CD 1. 

— StrongARM toolchain: GNU/C++ cross-hosted toolchain. You can invoke the 

toolchain utilities from a command shell or through the optional Embedded 

Linux IDE. 




This enables you to remotely develop and debug code running on the 

StrongARM on the IXP1200. You must install this from Volume II, CD 1. 

— Omni-NFS Server, optional. 

A 30-day trial version of an NFS server that makes directories located on a 

Windows NT platform visible to application code running on the StrongARM 

core processor. To use this optional software, you must install this from 

Volume II CD 1. 

— Linux IDE, optional. 

This supports application development, kernel debugging, and device driver 

development. It includes VMON as its debugger and boot loader. To use this 

optional software, you must install it from the Embedded Linux IDE CD-ROM 

Figure 1: Linux software configuration for the Intel IXDP1200 Advanced Development 

Platform using only a Windows NT development environment 



Windows NT 

platform 

Linux 

Microengine Toolchain: 

IXP1200 Microengine Development Environment 

StrongARM Toolchain: 

GNU C/C++ cross-compiler 

Linux IDE (optional) 

Figure 2: Linux software configuration for the Intel IXDP1200 Advanced Development 

Platform using both Windows NT and Linux development environments 



Windows NT 

platform 

Linux 

Microengine Toolchain: 

IXP1200 Microengine Development Environment 

StrongARM Toolchain: 

GNU C/C++ cross-compiler 

Linux IDE (optional) 

Linux 

platform 

Hardware 

Configuration 

To develop applications for the Embedded Linux environment using this release of 

the IXA SDK, you must have one of the hardware configurations described in the IXA 

SDK Installation and Setup Guide. There are three supported configurations for developers 

using Linux as the embedded operating system: 

l 

Configuration 1: Windows NT on the single-board computer on the Intel 

IXDP1200 Advanced Development Platform with an external keyboard and 

monitor attached. 






Single-board 

Computer 

Keyboard cable 

Serial 

Video cable 

Ethernet (see section on Ethernet connections) 

l 

Configuration 2: An external Windows NT workstation of your own choosing, in 

which case the single-board computer is not used. 



Windows NT Workstation 

Serial 


l 

Configuration 3: An external Linux workstation of your own choosing in addition 

to Windows NT on the single-board computer. 



Single-board 

Computer 

Serial 

Keyboard cable 

Video cable 


Linux workstation 

The connections in these configurations include: 

l 

A serial cable from the serial port of the IXM1200 Network Processor Base Card 

to the com port of the Windows NT platform to provide a remote serial console for 

the IXM1200 Network Processor Base Card. 



Components of the IXA SDK for the IXP1200 

l 

l 

Ethernet connections between the IXM1200 Network Processor Base Card and 

your chosen Windows NT and/or Linux development platforms as described in 

the IXA SDK Installation and Setup Guide. 

For remote debugging of the IXM1200 Network Processor Base Card, all configurations 

use the Ethernet connection. 

In configurations 1 and 3, video and keyboard cables from the single-board 

computer to your own external monitor and keyboard. 

Deploying 

Applications 

Most developers of IXA systems develop hardware and software simultaneously: 

l 

l 

OEMs develop boards and systems around the IXP1200 chip. 

Appliance vendors develop systems around an Intel board, the Policy Accelerator, 

which contains a complete IXP1200 subsystem. 

At the beginning of the development cycle, software developers work with a generic 

development system. Later in the development cycle, the software and hardware 

developers work together to integrate the software into the deployment hardware 

environment. 

To deploy an IXA application, you use the RAMdisk and flash utilities to create a 

flash image that contains both the application code you developed and an embedded 

Linux operating system. Depending on your deployment configuration, you download 

this image to the flash in the IXP1200 in the factory, or create an initialization or 

boot procedure to download it. 


The IXA SDK is designed specifically to develop IXA applications. It contains the 

tools, libraries, drivers, and other runtime elements that you use to develop, debug, 

and deliver embedded network applications. It also contains efficient languages for 

describing and classifying packets and for defining communication interfaces. 

The IXA SDK includes the following elements: 

l 

An application programming interface, the IXA API, which includes the 

following: 

— Object Management System (OMS) services library, which provides C support 

for interobject communication, ACE creation, and control of traffic flow. 

— The Action Services Library (ASL) core services, which provide C and C++ 

support for the packet-handling mechanism, and C support for data sets, 

event scheduling, and error handling. 

— The ASL application services, independent libraries which provide C and C++ 

support for efficient implementation of common packet-manipulation tasks, 

such as TCP/IP manipulation and reassembly, NAT, string searches in 

packets, ARP processing, and so on. These application building blocks speed 

development time. Additional libraries are made available from time to time. 

— The microACE Resource Manager API, which provides management services 

for microACEs and microengines and access to shared memory. 




— Microcode macros for use in microACE microblocks and dispatch loops. 

l 

l 

l 

System software, which includes the following: 

— The ACE runtimes for each ACE, which perform packet handling 

— The Object Management System (OMS), which acts as a name server and 

resource manager and provides the framework for interobject communication 

— The microACE Resource Manager, which manages microACE memory and 

coordinates communication between the core component and microblock in 

microACEs. 

— An embedded operating system (Linux, a widely-used, standard, open-source 

system) 

— A boot manager that performs power-on initialization 

— Device drivers 

— A TCP/IP protocol stack 

— Run-time libraries that provide execution and management services for the 

ACE model, name space, data handling, and interobject communication. 

Software development tools: 

— Network Classification Language (NCL), which you use to classify packets 

and direct actions to be taken. 

— An interface definition language, IXA IDL, in which you specify the crosscall 

interfaces that objects use to communicate through the OMS. 

— Linux compilers, assemblers, linkers, loaders, and debuggers for code in the 

various languages (C/C++, IDL, and NCL). 

— Command-line utilities for working with ACEs. 

— The IXP1200 Microengine Development Environment, a tool that supports the 

development and integration of microcode modules targeted for the microengines, 

the optimized packet processors on the IXP1200. This includes 

IXP1200 microcode, along with compilers, debuggers, and application development 

utilities. 

Predefined building blocks 

Example code and sample applications, reusable and modifiable library ACEs, 

predefined protocol descriptions, and other elements to make application development 

rapid. 



Chapter 2 

Elements of an Application 

This chapter introduces the languages and libraries that you use to build networking 

applications with the Intel ® IXA SDK. It describes the IXA system software that coordinates 

objects running on different processors, the C structures that support the ACE 

model, and the application building process. 


l “Overview” on page 19 

l “The Object Management System” on page 20 

l “ACEs and Support Structures” on page 22 

l “MicroACE Support Services” on page 24 

l “The Application Building Process” on page 25 

Overview 

The IXA SDK defines the active computing element (ACE), and provides an infrastructure 

and object-oriented environment that you use to develop applications using 

the ACE programming framework. 

Your application creates C structures and C++ objects for each independent ACE, and 

additional code in supporting languages such as Network Classification Language 

(NCL), IXA Interface Definition Language (IDL), and IXP1200 microcode. Each ACE 

can call API functions or predefined macros, as well as defining functions to perform 

the network service functionality that your application requires. 

The IXA SDK includes tools for programming the IXP1200 directly in microcode 

(assembly language), and also provides the infrastructure for integrating microcode 

with ACEs using the microACE architecture. 


Elements of an Application 19

The Object Management System 

A networking application that uses the ACE programming framework makes use of 

function libraries, macros, and so on that are provided with the SDK. Such an application 

includes source code in the following languages: 

Language Tools Libraries and predefined code 

C/C++ 

Gnu toolchain (gcc, ld, 

gdb, and so on) 

Object Management System 

(OMS), Action Services Library 

(ASL), Resource Manager, startup 

and configuration scripts 

IXP1200 microcode 

IXP1200 Microengine 

Development Environment 

IXP1200 packet-handling macros, 

microACE macros 

Network Classification 

Language (NCL) 

IXA Interface Definition 

Language (IDL) 

NCL compiler (nclcomp) 

IXA IDL compiler 

(tao_idl) 

TCP/IP protocol definitions 

The IXA SDK provides entire predefined ACEs that you can use as building blocks 

for rapid application development. These include the following: 

l 

l 

l 

The interface ACEs, system-defined microACEs that every application uses to 

receive and transmit packets on the network interface ports 

The stack ACE, which represents the Linux * TCP/IP stack 

Several library ACEs that perform typical networking tasks such as layer-three 

packet forwarding, layer-two bridging, and network address translation. 

For more information on the predefined ACEs, see Chapter 7, “Interface ACEs,” and 

Chapter 8, “Stack and Library ACEs.” 


The Object Management System (OMS), part of the IX system software, is a single 

logical entity with components distributed throughout the system. The OMS services 

are part of the IXA API. The management and control modules for an application use 

the global C functions defined by the OMS services to create, configure, control, and 

destroy objects and structures in all parts of the application, and to perform global 

tasks. The primary global services your application requires are: 

l 

l 

l 

Creating and destroying ACEs 

Defining and controlling packet flow using targets 

Communicating among ACEs and other programs with crosscalls 

Parts of the 

OMS 

The OMS contains the following parts: 

l 

The Resolver, which creates and deletes ACEs, and manages packet flow by 

binding ACEs and targets. 

20 Elements of an Application 



l 

The Name Server, which manages the name space for the OMS, maintaining a 

correspondence between names and internal identifiers for ACEs, targets and so 

on. The name space allows objects that might be distributed among processors to 

address one another unambiguously. 

The OMS also defines some general global functions to coordinate interobject 

communication through crosscalls. 

You typically set up both the development and delivery environments to start the 

OMS automatically on boot, so that it is always running. 

Accessing the 

OMS 

In order to communicate with the OMS, an object or program must create a communications 

channel in the form of a separate process or thread called a communication 

access process, or CAP. 

l 

l 

When you create an ACE, the initialization procedure automatically creates the 

CAP, and the ACE runtime polls that CAP for crosscall events in its main loop. 

You can access the CAP with the function ix_ace_to_cap. 

If your application contains other programs that need to communicate with the 

OMS (a manager program, for example), each such object must register with the 

OMS as a task. The task, like an ACE, contains a CAP, which you can access with 

the function ix_task_to_cap. The task’s main loop must poll for crosscall events 

on the CAP channel. 

Before you can create an ACE or task, you must create a CAP with which to make the 

Resolver calls. To create a CAP, use the ASL function ix_cap_init. Any application 

that needs to communicate with the OMS must include the ASL core services library, 

as well as the OMS services library, even if it does not use any ASL functions other 

than ix_cap_init. 

Naming 

Objects 

The Name Server provides a name space, which allows objects that might be distributed 

among processors to address one another unambiguously. The Name Server 

supports a hierarchical UNIX-like directory structure. The name of a target (for 

example) needs to be unique only within an ACE, and the name of the ACE needs to 

be unique only within an application-defined directory. 

To completely and uniquely identify an entity to the Name Server, you must use the 

full name, or complete path to the entity. You use the full name whenever you refer to 

an object using the OMS services. For example, a call to ix_res_bind must specify 

the full name of both the target and the ACE. 

For example, to create a binding between the default target in an ACE named MyAce 

and an ACE named ControlAce, in an application with no other name space directories 

defined, use the following full names in the ix_res_bind method: 

ix_res_bind (ressession, "/MyAce/default" , "/ControlAce"); 

For More 

Information 

l 

For more information on targets and bindings, see Chapter 5, “Controlling Packet 

Flow.” 



ACEs and Support Structures 

l 

l 

For more information on crosscalls, see Chapter 11, “Communication Within an 

Application.” 

For detailed reference information on OMS functions, see the IXA SDK Reference. 


The primary processing element on an IXA application is the ACE. An application 

can contain multiple ACEs to perform different processing operations, can start and 

stop ACEs at run time, and can change how packets flow from ports, through ACEs, 

and out of ports. 

The IXA SDK defines system ACEs to represent the physical network interfaces and 

the Linux TCP/IP stack, and library ACEs to perform typical network processing 

tasks. You define additional ACEs to process packets as needed by your application. 

Creating ACEs 

To define and create an ACE, you must first create the ACE single object executable. 

To do this: 

1. Define the ACE’s initialization phase in a C source file. This file must contain a 

definition for the initialization function ix_init. This function definition must, at 

least, allocate an ACE structure (ix_ace) and call ix_ace_init, which creates the 

ACE object. The function should also create and initialize any other structures 

that belong to the ACE, such as targets and sets. The file must also define a corresponding 

termination function (ix_fini) that cleans up the created structures. 

2. Define the ACE’s action phase in a C source file. The action code must contain 

definitions for the ACE’s action functions, which implement the handling and 

disposition of classified packets. 

3. Define the crosscall interfaces for interobject communication in an IXA IDL source 

file, compile it with the tao_idl compiler. This results in additional C source files 

for the ACE. See “Supporting Languages” on page 23. 

4. Define the ACE’s classification phase in an NCL source file. See “Supporting 

Languages” on page 23. 

5. Compile and link the initialization, action, and classification code into a single 

executable. (See Chapter 3, “Compiling and Testing Applications.”) 

An application’s manager program can create and initialize the application’s ACEs 

by calling Resolver functions in the OMS. To do this, it must first create a CAP 

channel through which to communicate with the Resolver. In the manager program: 

1. Create a CAP channel to the OMS using the ASL function ix_cap_init. 

2. Open a Resolver session by passing the CAP to the OMS function ix_res_open. 

3. Create the ACE using the function ix_res_create_ace, passing the Resolver 

session handle, the name of the ACE, and the path to the ACE executable in the 

development file system. 

You can also create ACEs from the command line or a script using the utility ixace. 

This utility creates a Resolver session and calls the ix_res_create_ace function. 




To create the ACE, the Resolver calls the initialization function you have defined in 

the ACE executable, and starts the ACE’s main loop, which polls continuously for 

packet arrival events and crosscall events. 

Support 

Objects 

The following table shows the C structures that can be part of an ACE. 

ASL structure 

Description 

ix_target 

ix_base_t 

ix_set 

ix_element 

ix_event 

ix_time 

Represents a packet destination target. You define targets 

in each ACE for all possible packet destinations. Each 

ACE is automatically initialized with one target, named 

default. 

l For more information, see Chapter 5, “Controlling 

Packet Flow.” 

Represents a crosscall interface. You must initialize each 

crosscall interface with this structure in both the server 

and the client before making any remote calls. 

l For more information, see Chapter 11, “Communication 

Within an Application.” 

Represents a data set, as defined in the ACE’s classification 

code. 

l For more information, see Chapter 13, “Using Sets of 

Data to Classify Packets.” 

Represents a data set member element. You modify this 

structure to contain your application-specific data. 

l For more information, see Chapter 13, “Using Sets of 


Represents a schedulable event. You define a callback 

function to be executed when a specified time has 

elapsed. 

l For more information, see Chapter 10, “Initializing and 

Acting on Packets in an ACE.” 

Represents a time value for scheduling events. 

l For more information, see the IXA SDK Reference. 

Additional 

Services 

Additional libraries extend the ASL to provide application services for TCP/IP 

packet manipulation. For more information, see the IXA SDK Reference. 

Supporting 

Languages 

The IXA SDK includes two languages, Network Classification Language (NCL), and 

IXA Interface Definition Language (IDL), that you use to create some of the source 

code for an ACE. 

Elements of an Application 23 


MicroACE Support Services 

l 

l 

An ACE classifies incoming packets according to rules and protocol definitions 

that you write in NCL. For more information, see Chapter 9, “Classifying Packets 

Using NCL.” 

ACEs and other objects communicate using a remote procedure call mechanism 

called a crosscall. You define the interfaces for the crosscalls in IXA IDL. For more 

information, see Chapter 11, “Communication Within an Application.” 

Error Handling 

Most API functions return an error token, which is a value of type ix_error. An error 

token of zero indicates that the function was successful. When a call is unsuccessful, 

it returns a non-zero token that is associated with a descriptive string giving information 

about the failure. 

The ASL defines a set of functions for retrieving the messages associated with error 

tokens, and a set of macros that provide additional context information for errors. It 

also provides functions you can use to add your own uniquely numbered error codes 

to provide information about failed operations in your own functions. 

l 

l 

The error handling functions and macros are describe in Chapter 4, “The ASL 

Core Support Package API,” of the IXA SDK Reference. 

The predefined error codes are listed and described in Appendix A, “IXA API 

Error Codes,” of the IXA SDK Reference. 

MicroACE Support Services 

Conventional ACEs run on a general-purpose processor. To achieve higher performance, 

ACEs can use other special-purpose processors for acceleration. An ACE that 

offloads fast-path processing to an IXP1200 microengine is known as a microACE. 

A microACE combines a core component, a complete ACE that runs on the core 

processor, with a microblock. 

1. Write the microblock in microcode, the assembler language for the IXP1200 

microengines. 

2. Combine several microblocks with a dispatch loop, also in microcode, that defines 

a packet processing pipeline for a microblock group. 

3. Compile the microblocks and dispatch loop into a single-object image (a .uof file) 

that runs on a single microengine. 

To write and compile microcode, use the IXP1200 Microengine Development Environment. 

The IXP1200 microcode documentation is accessible from the following 

directory: 

C:IXP1200\documentation\IXP1200 Documentation 

MicroACEs and their managing programs communicate with the microengines 

using the Resource Manager. The Resource Manager is system software that runs in the 

core processor kernel. It does resource allocation for memory that is shared by the 

core processor and the microengines, and also handles packet demultiplexing and 

other system-level microengine management problems. 



The Application Building Process 

The Resource Manager defines a C-language API, which you can use in an ACE 

management program or in ACE code to set up microACEs and manage the shared 

memory resources. 

The IXA SDK also defines a number of microcode macros that specifically support 

the microACE programming framework. Use these in the microblocks and the 

dispatch loop to define and access global variables in the shared memory, to manipulate 

packet buffers, and to pass packets between the microengine and the core 

processor. 

l 

For more information on microACEs and their supporting system software, see 

Chapter 6, “Writing MicroACEs.” 


The following gives a rough picture of the process you use to define all of the parts 

of an IXA application, with references to places you can find more information on 

each piece. 

1. Define your services at a high level, and decide how to implement them with 

conventional ACEs, microACEs, and standard application programming. 

2. Sketch packet flow among the ACEs and decide what targets you will need and 

how to bind them. 

3. For the microACEs: 

a. Implement the microblocks for each microACE using the IXP1200 

Microengine Development Environment. 

b. Write a dispatch loop to implement the microcode packet pipeline for each 

microblock group. 

c. Create a microcode image for each microengine by compiling and linking the 

microblocks in each group (including those for the interface ACEs and library 

ACEs you are using) with the dispatch loop, using the IXP1200 Microengine 

Development Environment. 

For more information, see Chapter 6, “Writing MicroACEs.” 

4. Implement the classification rules for each ACE in NCL. 

a. Define protocols and predicates. You can include the standard TCP/IP 

protocol, which is predefined and provided as part of the IXA SDK. 

b. Define data sets and searches. For more information, see Chapter 13, “Using 

Sets of Data to Classify Packets.” 

c. Define rules that call action functions. This will help you define the names and 

signatures of the action functions, which you will define later. 

For more information, see Chapter 9, “Classifying Packets Using NCL.” 

5. Implement action code for each ACE in C, defining the action functions called by 

the rules. 

For more information, see Chapter 10, “Initializing and Acting on Packets in an 

ACE.” 




6. Define the crosscalls with which ACEs and the manager program will communicate: 

a. Define crosscall interfaces in IXA IDL. 

b. Compile the interface definitions with the IXA IDL compiler tao_idl. This 

produces a set of C headers and source files that define crosscalls and crosscall 

references. 

c. Edit the generated crosscall source to define the call methods. 

d. If needed, edit the generated callback sources to define callbacks for asynchronous 

calls. 

For more information, see Chapter 11, “Communication Within an Application.” 

7. Implement initialization code for each ACE in C. 

a. Define an initialization function to create the ACE and its related objects 

(targets, sets, and so on). See “Creating ACEs” on page 22. 

b. Define methods and utility functions. 

c. Include the crosscall headers as needed (depending on whether the ACE is 

acting as a call server or call client). Initialize each crosscall interface in both 

the server and the client. See Chapter 11, “Communication Within an Application.” 

8. Create the ACE executable for each ACE. 

a. Compile the NCL code using nclcomp, then gcc. 

b. Compile the action, initialization, and crosscall code using gcc. 

c. Link the rules object, action object, initialization object, and crosscall objects 

using ld. 

You typically use a makefile to do this. For more information, see Chapter 3, 

“Compiling and Testing Applications.” 

9. Modify the startup script’s configuration file, ixsys.config: 

a. Specify and configure the ports you are using. 

b. Create and start the microACEs, specifying a microcode image for each type 

of port. 

c. Create and start the conventional ACEs, passing in a pointer to the single 

object executable. 

d. Bind targets and ACEs to determine packet flow in the application. 

e. Run the configuration scripts for any library ACEs you are using. 

For more information, see Chapter 4, “Configuring and Starting IXA Systems.” 

10. Create a runtime, downloading the application and operating system to IXP1200 

flash. For the development system: 

a. Open a remote shell to the IXDP1200 Advanced Development Platform from 

the Linux development workstation. 

b. Mount the workstation’s NFS directory on the IXP200. 




c. Copy all executables to the IXP1200’s NFS directory. 

11. Run the startup script, ixstart, from the command line of the remote shell. 

Elements of an Application 27 





Chapter 3 

Compiling and Testing Applications 

This chapter describes each of the compilation steps in detail to help you understand 

the compilation model for ACEs and IXA applications. 


l “Overview of the ACE Compilation and Linking Process” on page 29 

l “Compiling MicroACEs” on page 32 

l “Using Makefiles” on page 33 

l “Debugging an Application” on page 33 

Overview of the ACE Compilation and Linking Process 

To create an ACE single-object executable file, you compile and link several source 

files using the GNU tools, NCL compiler, and IXA IDL compiler. Source files include: 

l 

l 

l 

C/C++ files for initialization code and action functions 

NCL files for classification rules 

IXA IDL files for crosscall interfaces, which compile to additional C files for the 

crosscall source code 

Your application uses makefiles and scripts to ensure that all of an application’s files 

are compiled, linked, and loaded in the correct manner and order. 

A microACE has, in addition to these ACE source files that define the core component, 

a microcode source file that defines the microblock. See “Compiling 

MicroACEs” on page 32. 

Intermediate 

Compilation 

A conventional ACE contains rules written in NCL. Compile the NCL file to an intermediate 

.s file using the NCL compiler, nclcomp. Compile the intermediate file to a 

.o linkable object with the GNU C/C++ compiler, gcc. 

Compiling and Testing Applications 29 



The names of all cross-compilation utilities are prefixed with target platform information. 

For the StrongARM * core processor on the IXP1200, the prefix is armv4bunknown-linux-. 

For example, to create an executable for an ACE to run on the core 

processor, use the cross compiler armv4b-unknown-linux-gcc. 

When using crosscalls, you must provide crosscall interfaces written in IXA IDL. 

Compile .idl source files to .c and .h files using the IDL compiler, tao_idl. Include 

the header files as needed in the ACE initialization code source, depending on 

whether the ACE acts as a crosscall server or client. (See Chapter 11, “Communication 

Within an Application.”) Compile and link the crosscall source files into the ACE 

executable, using gcc and ld. 

l 

l 

For a crosscall server, link in the crosscall source file. 

For a crosscall client, link in the stub (crosscall reference) source file, and, if there 

are deferred calls, the callback source file. 

Compiling and 

Linking Source 

Files 

A conventional ACE contains initialization code written in C/C++, which creates 

and initializes the ACE object and related structure, and action code written in C, 

which defines the action functions. Compile the source files for both these parts into 

.o linkable objects using the GNU C/C++ compiler, gcc. 

Finally, link the rules, action, and initialization objects into a single object ACE 

executable file, using the GNU linker, ld. When you create the ACE (using either the 

Resolver ix_res_create_ace function in a management program or the ace 

keyword in a system configuration file), you specify the path to this executable. See 

Chapter 4, “Configuring and Starting IXA Systems.” 

The following figure shows the general flow of application files through the compilation 

process. 

30 Compiling and Testing Applications 



Manager 

program 

C code 

mgr.c 

stub.c 

ASL 

gcc, ld 

mgr.o 

IXA IDL code 

ccif.idl 

tao_idl 


code 

NCL code 

rules.ncl 

C code 

actions.c 

init.c 

cc.c 

ASL 

nclcomp 

gcc 

rules.s 

rules.o 

actions.o 

init.o 

cc.o 

ld 

ace.o 

For more information on options available during compilation and linking, see: 

l Chapter 7, “Command-Line Tools,” in the IXA SDK Reference 

l Publicly available GNU C/C++ tool documentation 

Compiling 

Kernel ACEs 

During development, all conventional ACEs run in user space, so that you can test 

and debug them. When you deliver an application, however, you can choose to run 

a conventional ACE that is in the critical path in kernel space for maximum performance. 

If you intend to compile an ACE for the kernel, you must write it entirely in 

C, not C++. 

Although conventional ACEs generally do exception processing, while microACEs 

handle fast-path packet processing, some kinds of exception processing are more critical 

than others. For example, an ACE that processes new TCP sessions would need 

to be optimized for performance, while one that counts errors would not affect the 

overall efficiency of the application. 



Compiling MicroACEs 

Compiling MicroACEs 

A microACE contains a core component, for which you build a single-object 

executable in the same way as for a conventional ACE. In addition, each 

microACE contains a microblock. The source for the microblock can be: 

l 

l 

A microcode .uc file. 

A Micro C file compiled to microcode. 

You define a microblock group to run on each microengine and write a microcode 

dispatch loop to define the packet processing pipeline in the group. Use 

the IXP1200 Microengine Development Environment to compile and link all of 

the microblocks in the group, together with the microcode file for the dispatch 

loop, into a microcode image (.uof file) for a single microengine. 

You must specify the microcode image to be used for each type of port, such as 

10/100BaseT Ethernet input or gigabit Ethernet output. To do this, you can 

modify the startup script’s configuration file (ixsys.config), or use the 

Resource Manager function RmUengSetUcode as part of your own ACE initialization 

and management program. You can run the same image on more than 

one microengine, or different images on each. The Resource Manager allocates 

the threads on the microengines. 

The type of a microcode image is determined as shown in the following table: 

Type 

Slow ingress 

Slow egress 

Fast ingress 

Fast egress 

Other 

Description 

The image contains the microblock for the input interface ACE, configured 

for 10/100BaseT ports. 

The image contains the microblock for the output interface ACE, configured 



for gigabit ports. 



The image does not contain an interface ACE microblock. 

l For more information on writing and starting microACEs, see Chapter 4, 

“Configuring and Starting IXA Systems,” and Chapter 6, “Writing 

MicroACEs.” 

l 

For more information on creating and configuring interface ACEs, see 

Chapter 7, “Interface ACEs.” 



Using Makefiles 

l 

The microengine toolchain and the IXP1200 Microengine Development Environment 

are documented in the IXP1200 documentation set. 

Using Makefiles 

The UNIX make utility provides the most effective way to ensure that all of an application’s 

files are compiled and linked in the correct manner and order. 

You can issue compilation and linking commands directly from the command line in 

a command shell, but you typically use a makefile to compile and link your application. 

Makefiles are designed to handle dependencies in compilation order and variations 

in the names and locations of tools and source files. 

For information on compilation and linking options, see: 

l Chapter 7, “Command-Line Tools,” in the IXA SDK Reference 

l 

Publicly available GNU C/C++ tool documentation 

Debugging an Application 

Use the GNU debugger, gdb, to test and debug your IXA application. This debugging 

tool is provided as part of the IXA SDK distribution. 

You can use GDB on your x86 Linux * host to remotely debug applications running on 

the IXDP1200 Advanced Development Platform. For example, to debug a file 

myfile.c: 

1. Compile myfile.c with the big-endian ARM * toolchain version of gcc with the - 

g option. 

2. Open a remote shell for the IXP1200 on the Linux host using Minicom, or on a 

Windows NT * host using Hyperterm. 

3. Transfer the binary for myfile into the RAMdisk of the IXP1200 using FTP or NFS. 

4. In a command shell for the IXP1200, type: 

gdbserver hostip_addr:port_number myfile arguments 

For example: 

gdbserver 10.3.19.128:12345 myfile 

5. On the host, go to the source directory for myfile, then start GDB on the file: 

cd /mydir 

gdb myfile 

NOTE: 

You can use the front-end GUI provided by Red Hat. To do this, invoke GDB 

with xxgdb myfile, rather than gdb myfile. 



Debugging an Application 

6. At the GDB prompt, connect to the IXP1200 target: 

target remote IXP1200_ipaddr:port_number 

7. At this point, the program is running and you can begin using the debugger. 

— Type list to see the code. 

— After setting a breakpoint, type continue (not run). 

For more information on how to use GDB, see publicly available GNU tool documentation. 



Chapter 4 

Configuring and Starting IXA Systems 

This chapter describes how to start an IXA system with a particular port configuration 

and launch the application’s system ACEs, library ACEs, and user ACEs. 



l “Using Startup Scripts and Configuration Files” on page 36 

l “The System Configuration File” on page 37 

l “Setting Up Particular Configurations” on page 39 

l “Launching Application ACEs” on page 46 

Overview 

Typically, you start the system software automatically as part of booting the 

IXDP1200 Advanced Development Platform. To do this, you call a startup script, 

which in turn calls other scripts. The scripts use configuration files, which you 

modify to configure your application’s port usage and to load, configure, and start 

the system, library, and user ACEs for your application. 

The default system initialization startup script (SDKinstallpath/bin/armbe/ixstart) 

loads the IXA SDK components and drivers and sets up the necessary 

Linux * device entries. It then runs the configuration utility ixconfig. This utility 

reads the system configuration file, SDKinstallpath/bin/arm-be/ixsys.config. 

l 

l 

You must modify the system configuration file to configure the ports and interface 

ACEs. The script starts the interface ACEs. See “Using Startup Scripts and Configuration 

Files” on page 36. 

You must specify any microACEs you want to start in the system configuration 

file, and specify where to find the compiled microcode images for your application. 

The script starts the microengines and the microACEs. 


Configuring and Starting IXA Systems 35

Using Startup Scripts and Configuration Files 

l 

l 

You can modify the system configuration file to run other startup scripts, such as 

those supplied for the library ACEs. See “Setting Up Particular Configurations” 

on page 39. 

You can modify the system configuration file to start user ACEs, either directly 

(using the ace keyword) or by running the ixsh utility. See “Launching Application 

ACEs” on page 46. 

For Additional 

Information 

l 

l 

l 

For information on the system and library ACEs, see Chapter 7, “Interface 

ACEs,” and Chapter 8, “Stack and Library ACEs.” 

For detailed reference information on the keywords and syntax of the configuration 

files, see the IXA SDK Reference. 

Configuration files for sample applications that use various combinations of 

library ACEs can be found in the following location: 

SDKinstallpath/src/microace/apps 

Using Startup Scripts and Configuration Files 

The IXA SDK provides sample scripts and configuration files that start and configure 

the interface ACEs and other library ACEs in typical configurations. These files are 

fully commented. To start a particular configuration of ports and ACEs, including 

interface ACEs and some set of library and user ACEs, you use the supplied startup 

scripts, modifying their configuration files for your application and configuration. 

The basic procedure for starting and exiting the IXA system is as follows: 

1. Determine the addresses for your network topology, and modify the system 

configuration file, ixsys.config, to set up the port configuration 

2. Create the necessary configuration files for the library ACEs you are using: 

— For the L2 bridging ACE, modify l2bridge.config. 

— For the L3 forwarder ACE, modify l3forwarder.config. 

— For the NAT ACE, modify nat.config. 

3. Add sh commands to the system configuration file, ixsys.config, to run the 

startup script for each included library ACE, specifying the ACE name and 

configuration file you have created for each one. 

4. After booting the IXDP1200 Advanced Development Platform, run the startup 

script in the command shell: 

$ ./ixstart 

5. To shut down the modules, run the termination script in the command shell: 

$ ./ixstop 

36 Configuring and Starting IXA Systems 


The System Configuration File 

Starting and 

Initializing 

Interface ACEs 

When you invoke startup script at system boot it does the following: 

l 

l 

l 

l 

Activates the specified ports. 

Sets up and starts the input and output interface ACEs according to the specified 

configuration. 

Configures and enables the microengines using Resource Manager calls. 

Starts threads on the microengines for each port. 

Microengine 

Threads 

The configuration script associates each port to be used with one of the six IXP1200 

microengines. The script starts the appropriate threads on each microengine, 

according to the ports associated with it, so that enough threads are available for each 

port. 

l 

l 

l 

Each microengine has four threads. 

One gigabit port requires eight threads, so it takes two 2 input microblock groups 

to handle it. 

One 10/100BaseT port requires one thread, so a microengine can handle up to 

four such ports. 

For example, an 8/1 configuration could use two microengines for input on the 

gigabit port, and two for input on the 8 10/100BaseT ports. This leaves two microengines 

to handle output for all ports. 


The system configuration file specifies the following information for use by the 

startup script: 

l 

l 

l 

l 

l 

l 

Which ports to use, and their IP address information. 

The microcode image to be loaded on each microengine. 

The configuration for the input and output interface ACEs. 

Other microACEs to be started, including stack and library ACEs your application 

will use. 

Bind configurations for microACEs (both static and dynamic) 

Shell commands to run. Run the ixsh utility to create, run, and bind conventional 

ACEs, and run other configuration scripts. 

The following annotated system configuration file shows how to start and configure 

the network interfaces and ACEs. This example loads the L3 forwarder library ACE, 

stack ACE, and input and output ACEs. It sets up binding such that the forwarder 

receives packets directly from the input ACE and sends them directly to the stack 

ACE and the output ACE. 




Configuring 

Network 

Interfaces 

# ixsys.config 

# ********************************************************* 

# Setup file for the ixconfig application that configures the 

# L3Fwdr library ACE, stack ACE, and interface ACEs 

# Specifies: 

# - Network interfaces to be started at system boot 

# - MicroACEs to be started at system boot (interface, L3Fwdr) 

# - Conventional ACEs to be started at system boot (stackAce) 

# - Bind configuration 

# - Shell commands to be run 

# ********************************************************* 

# 

# Specify interfaces 

interface 0 10.1.0.1 10.1.0.255 255.255.255.0 00:01:02:03:04:05 0 

interface 1 10.2.0.1 10.2.0.255 255.255.255.0 00:01:02:03:04:06 0 

interface 2 10.3.0.1 10.3.0.255 255.255.255.0 00:01:02:03:04:07 0 

interface 3 10.4.0.1 10.4.0.255 255.255.255.0 00:01:02:03:04:08 0 

interface 4 10.5.0.1 10.5.0.255 255.255.255.0 00:01:02:03:04:09 0 

interface 5 10.6.0.1 10.6.0.255 255.255.255.0 00:01:02:03:04:10 0 

interface 6 10.7.0.1 10.7.0.255 255.255.255.0 00:01:02:03:04:11 0 

interface 7 10.8.0.1 10.8.0.255 255.255.255.0 00:01:02:03:04:12 0 

interface 16 10.17.0.1 10.17.0.255 255.255.255.0 00:01:02:03:04:21 0 

NOTE: 

These lines tell the ixconfig script to run nine network interfaces. The first 

eight (0-7) are 10/100BaseT Ethernet ports, the last (16) is a gigabit Ethernet 

port. The ixconfig script uses this information to pass the appropriate 

configuration parameters when it creates the input and output microACEs. 

Identifying 

Microcode 

Images 

# ********************************************************** 

# Specify the microcode image (.uof) files 

file 0 ./SlowIngressL3.uof 

file 1 ./SlowEgressRR.uof 

file 2 ./FastIngressL3-seq1.uof 


file 4 ./FastEgressFifo.uof 

NOTE: 

These lines tell the ixconfig script which microcode image files to load. 

Each microcode image combines the microblocks for the input ACE and the 

L3Fwdr ACE with a dispatch loop. 

The IXA SDK also provides microcode image files that combine input, L2 

bridging, L3 forwarding, and NAT. The ixconfig script uses the Resource 

Manager library to load the code to the microengines. 

Starting and 

Configuring 

Aces 

# ************************************************************** 

# Specify the microACEs 

microace ifaceInput ./ingressAce none 0 1 

microace ifaceOutput ./egressAce none 1 2 

microace L3Fwdr ./l3_forward_ace none 0 3 ifaceInput 



Setting Up Particular Configurations 

NOTE: 

These lines tell the ixconfig script to launch three microACEs: the input, 

output, and L3Fwdr ACEs. The script uses the specified ACE single object 

file names to launch the core components of the microACEs. For example, 

l3_forward_ace is the ACE single object file name for the core component 

of the L3fwdr ACE. The ixconfig script uses OMS calls to create the new 

ACEs. 

# ************************************************************* 

# Specify the conventional ACEs (such as stack ACEs) 

ace stackAce ./kstack none 3 ifaceInput 

NOTE: 

This line tells the ixconfig script to launch the stack ACE, using the 

specified ACE single object file name, kstack. The ixconfig script uses 

OMS calls to create the new ACE. 

# ************************************************************** 

# Specify the bindings 

bind static ifaceInput/default L3Fwdr 

bind static L3Fwdr/out_if ifaceOutput 

bind regular L3Fwdr/out_if ifaceOutput 

bind regular L3Fwdr/stack stackAce 

bind regular stackAce/tx ifaceOutput 

NOTE: 

These lines tell the ixconfig script to bind the three microACEs statically as 

specified in the dispatch loop. They also creates dynamic bindings from the 

forwarder to the output ACE and stack ACE, and from the stack ACE to the 

output ACE. The ixconfig script uses OMS calls to create the bindings. 

# ************************************************************* 

# Run the startup scripts for the stack ACE 

# and L3 forwarding ACE. 

sh ./stackconfig ./ixsys.config 

sh ./l3config L3Fwdr ./ixsys.config ./route.config-sys-l3fwdr 

NOTE: 

These lines tell the ixconfig script to run the stackconfig utility to 

configure the stack ACE with the interface information, and to run the 

l3config utility to set up a simple route table. These utilities are in the same 

directory as ixsys.config. The l3config utility uses the forwarder’s configuration 

crosscalls to add a basic set of routes, as specified in the file 

route.config-sys-l3fwdr. 


This section shows how to set up the configuration files when using the library ACEs 

for specific tasks. It shows the following examples: 

l “Configuring an L2 Bridge” on page 40 




l “Configuring an L3 Forwarder” on page 42 

l “Configuring an L3 Forwarder with NAT” on page 44 

NOTE: 

In these examples, all the commands are executed from a single directory 

containing all the executables and script files. If your files are in different 

locations, you must specify the paths relative to the execution directory. 

Configuring an 

L2 Bridge 

This example shows how to configure the IXDP1200 Advanced Development Platform 

to act as a layer 2 bridge for the fast Ethernet and gigabit Ethernet ports. 

System Configuration File 

The system configuration file sets up eight octal ports (ports 0-7) and 1 gigabit port 

(port 16). 

l 

l 

On LAN segments connected to ports 0 and 1, there are two fixed nodes that will 

not move to a new LAN segment, with MAC addresses 00:aa:bb:cc:dd:00 and 

00:aa:bb:cc:dd:01 respectively. 

On the segments connected to other ports, the MAC addresses of connected nodes 

are not known at startup. 

IXP1200 Evaluation Platform (L2 Bridge) 

0 1 2 3 4 5 6 7 16 

10.1.0.0/16 

10.4.0.0/16 

10.2.0.0/16 

10.6.0.0/16 

10.3.0.0/16 

10.7.0.0/16 

10.4.0.0/16 

10.8.0.0/16 

10.17.0.0/16 

This configuration file also starts and binds the L2 bridging library ACE, and tells the 

system startup script to run the L2 bridging configuration script. 


# Configure ports 

interface 0 11.2.10.51 11.2.10.255 255.255.255.0 08:02:03:04:05:06 1 

interface 1 11.2.10.52 11.2.10.255 255.255.255.0 08:02:03:04:05:07 1 

interface 2 11.2.10.53 11.2.10.255 255.255.255.0 08:02:03:04:05:08 1 

interface 3 11.2.10.54 11.2.10.255 255.255.255.0 08:02:03:04:05:09 1 

interface 4 11.2.10.55 11.2.10.255 255.255.255.0 08:02:03:04:05:0A 1 

interface 5 11.2.10.56 11.2.10.255 255.255.255.0 08:02:03:04:05:0B 1 

interface 6 11.2.10.57 11.2.10.255 255.255.255.0 08:02:03:04:05:0C 1 

interface 7 11.2.10.58 11.2.10.255 255.255.255.0 08:02:03:04:05:0D 1 

interface 16 11.2.10.67 11.2.10.255 255.255.255.0 08:02:03:04:05:16 

1 

# This line is optional 

mode 0 




# Specify the microcode image files 

file 0 ./SlowIngressL2L3NAT.uof 


file 2 ./FastIngressL2L3NAT-seq1.uof 






microace L2Bridge ./l2bridge_ace none 0 4 


bind static ifaceInput/default L2Bridge 

bind static L2Bridge/out_if ifaceOutput 

bind regular L2Bridge/out_if ifaceOutput 

# Specify the shell command to run the L2 bridge startup script. 

sh ./l2config L2Bridge ixsys.config l2bridge.config 

L2 Bridging Configuration File 

The L2 bridging configuration file adds static forwarding entries to the routing table 

and sets up the corresponding port configuration for the L2 bridging ACE. 

# l2bridge.config 

# add forwarding entries 

add_fwd_static_entry 0 00:aa:bb:cc:dd:00 

add_fwd_static_entry 1 00:aa:bb:cc:dd:01 

# set port configuration 

set_port_state 0 5 









enable_port_bridging 0 









set_port_mtu 0 1518 



Configuring and Starting IXA Systems 41 










L3 Forwarder 


to act as a layer 3 forwarder for an IP network. This simple example sets up 

static routes, populating the routing table using the L3 forwarder configuration 

script. The application would use the L3 forwarder’s crosscalls to manage the routing 

table at run time. 


This example configures eight octal ports (ports 0-7) and 1 gigabit port (port 16). 

l Each port is on a different LAN segment and each LAN segment is a different 

network, like an enterprise-wide router. 

l 

The default gateway is 192.10.11.12 and is on network 192.10.11.0, connected to 

port 1. 

IXP1200 Evaluation Platform (L3 Forwarder) 

0 1 2 3 4 5 6 7 16 

10.1.0.0/16 

192.10.11.0/24 

(Gateway) 

10.1.128/24 

10.1.192/24 

10.1.224/24 

10.3.0.0/24 

10.4.0.0/24 

Router 

10.5.0.0/24 

10.6.0.0/24 

10.7.0.0/24 

10.8.0.0/24 

10.17.0.0/24 

This configuration file also starts and binds the L3 forwarder library ACE, and tells 

the system startup script to run the L3 forwarder configuration script. 



interface 0 10.1.0.1 10.1.0.255 255.255.255.0 00:01:02:03:04:05 0 

interface 1 192.10.11.1 192.10.11.255 255.255.255.0 

00:01:02:03:04:06 0 

interface 2 10.3.0.1 10.3.0.255 255.255.255.0 00:01:02:03:04:07 0 

interface 3 10.4.0.1 10.4.0.255 255.255.255.0 00:01:02:03:04:08 0 

interface 4 10.5.0.1 10.5.0.255 255.255.255.0 00:01:02:03:04:09 0 

interface 5 10.6.0.1 10.6.0.255 255.255.255.0 00:01:02:03:04:10 0 

interface 6 10.7.0.1 10.7.0.255 255.255.255.0 00:01:02:03:04:11 0 

interface 7 10.8.0.1 10.8.0.255 255.255.255.0 00:01:02:03:04:12 0 




interface 16 10.17.0.1 10.17.0.255 255.255.255.0 00:01:02:03:04:20 0 

# Specify the microcode images 

file 0 ./SlowIngressL3.uof 









# Specify the conventional ACEs - in this case, the stack ACE 



bind static ifaceInput/default L3Fwdr 


bind regular L3Fwdr/out_if ifaceOutput 

bind regular L3Fwdr/stack stackAce 

bind regular stackAce/tx ifaceOutput 

# Run the startup scripts for stack ACE and L3Fwdr 



#end of ixsys.config 

L3 Forwarder Configuration File 

The L3 forwarder configuration file adds static routes to the forwarding table and sets 

up the default route and gateway. 

# l3forwarder.config 

# route information for the L3 forwarder 

routeadd 10.1.0.0 255.255.0.0 0.0.0.0 0 

routeadd 192.10.11.0 255.255.255.0 0.0.0.0 1 

routeadd 10.3.0.0 255.255.255.0 0.0.0.0 2 

routeadd 10.4.0.0 255.255.255.0 0.0.0.0 3 

routeadd 10.5.0.0 255.255.255.0 0.0.0.0 4 

routeadd 10.6.0.0 255.255.255.0 0.0.0.0 5 

routeadd 10.7.0.0 255.255.255.0 0.0.0.0 6 

routeadd 10.8.0.0 255.255.255.0 0.0.0.0 7 

routeadd 10.17.0.0 255.255.255.0 0.0.0.0 16 

#default route and gateway 

routeadd 192.10.11.5 255.255.255.0 0.0.0.0 1 

routeadd 0.0.0.0 0.0.0.0 192.10.11.5 1 

#end of configuration. 





L3 Forwarder 

with NAT 


to act as a router with NAT functions, as would typically be used on the border 

between two or more networks. 

The example sets up the same network topology described in “Configuring an L3 

Forwarder” on page 42, adding NAT functionality 

l 

l 

The 192.10.11.0 network is the external network—that is, the IP addresses on this 

network are globally unique. The other networks are internal to the site. 

— The IP address of port 1 on the 192.10.11.0 network is 192.10.11.10. 

— The site uses the IP addresses from 192.10.11.50 through 192.10.11.60 as global 

unique IP addresses to be used by the internal nodes. 

The 10.1.0.0 network is subnetted into 10.1.128.0, 10.1.192.0, 10.1.224.0 networks. 

This example configures the NAT library ACE to enforce the following policies on the 

traffic between the external network and 10.1.0.0 network: 

l 

l 

l 

l 

Translate 10.1.0.10 to 192.10.11.50 and the reverse. 



For hosts from the 10.1.128.0 network, map to 192.10.11.53 address and the 

reverse. 

l For hosts from the 10.1.192.0 network, dynamically map to addresses 192.10.11.54 

through 192.10.11.58. 

l 

l 

For requests coming onto 192.10.11.10, TCP/UDP port 1000, load balance the 

requests, alternating between the nodes 10.1.30.5 and 10.1.30.6. 

Drop packets that are destined to IP addresses greater than 10.1.30.10 and less 

than 10.1.30.40. 

l Pass all packets originating from 10.5.0.0. 


This example configures eight octal ports (ports 0-7) and 1 gigabit port (port 16). It 

starts and binds the following ACEs, in addition to the interface ACEs: 

l 

l 

l 

l 

the L3 forwarder library ACE 

the L2 bridging library ACE 

the NAT library ACE 

the stack ACE. 

The file then tells the system startup script to run the configuration scripts for all of 

these ACEs. 



interface 0 10.1.0.1 10.1.0.255 255.255.255.0 00:01:02:03:04:05 0 

interface 1 10.2.0.1 10.2.0.255 255.255.255.0 00:01:02:03:04:06 0 




interface 2 10.3.0.1 10.3.0.255 255.255.255.0 00:01:02:03:04:07 0 

interface 3 10.4.0.1 10.4.0.255 255.255.255.0 00:01:02:03:04:08 0 

interface 4 10.5.0.1 10.5.0.255 255.255.255.0 00:01:02:03:04:09 0 

interface 5 10.6.0.1 10.6.0.255 255.255.255.0 00:01:02:03:04:10 0 

interface 6 10.7.0.1 10.7.0.255 255.255.255.0 00:01:02:03:04:11 0 

interface 7 10.8.0.1 10.8.0.255 255.255.255.0 00:01:02:03:04:12 0 

interface 15 10.16.0.1 10.16.0.255 255.255.255.0 00:01:02:03:04:20 0 

# Specify microcode images 

file 0 ./SlowIngressL2L3NAT.uof 









microace nat ./Nat none 0 5 natc 3 

# Specify the convention ACEs: stack ACE and NAT ACE 


ace natc ./natctlr none 2 nat 1 

# Specify bindings 

bind static ifaceInput/default nat 


bind static L2Bridge/default nat 

bind static nat/PASS 

L3Fwdr 

bind regular nat/CONFIG 

bind regular L3Fwdr/stack 

bind regular stackAce/tx 

bind regular natc/default 

natc 

stackAce 

ifaceOutput 

nat 

# Run startup scripts for stack ACE, L3Fwdr ACE, and NAT ACE 



sh ./natconfig natc ./nat_l2l3nat.config 

#end of ixsys.config 

NAT Configuration File 

This example sets up the NAT configuration rules described above. 

# nat.config 

# create filter ACL 

acl_create 0 0 

# create NAT ACL 



Launching Application ACEs 

acl_create 1 1 

#filter rules here 

filter 0 DROP IPDEST > 10.1.30.10, IPDEST < 10.1.30.40 

filter 0 PASS IPSRC = 10.5.*.* 

# nat action rules 

filter 0 NAT IPSRC > 10.1.0.9 , IPSRC < 10.1.0.13 

filter 0 NAT IPSRC = 10.2.*.* 

filter 0 NAT IPSRC = 10.3.*.* 

filter 0 NAT IPDST = 192.10.11.10 , DSTPORT = 1000 

# drop the rest of packets 

filter 0 DROP IPSRC=*.*.*.* 

# nat rules 

nat_static 1 IPSRC = 10.1.0.10 with 192.10.11.50 



nat_ip_masquerade 1 IPSRC = 10.1.128.* with 192.10.11.53 

nat_dynamic 1 IPSRC = 10.1.192.* with 192.10.11.54 4 

nat_virtual_server 1 IPDEST = 192.10.11.10, DESTPORT = 1000 with 

10.1.30.510.1.30.6 

#end of nat.config 

Launching Application ACEs 

During development, you might need to load and start application ACEs interactively. 

To run and test an application, you must load and run ACEs and create the 

bindings that control traffic flow. You can do this from the command line, in a script, 

or from a manager or launcher program. Similarly, you can stop ACEs and change 

binding in any of these ways. 

l 

l 

To launch and control the application ACEs from a script or the command line, 

use the ixsh utility provided in $IXROOT/bin/. This utility is described in 

Chapter 8, “Command-Line Tools,” in the IXA SDK Reference. 

To launch and control an application ACE from a manager or launcher program, 

do the following: 

a. Open a CAP in its own thread, and use it to open a Resolver session. 

b. To start an ACE, call the function ix_res_create_ace, passing the Linux path 

to the ACE executable. 

c. To bind targets and ACEs, call the function ix_res_bind. Use ix_res_unbind 

to change the traffic flow. 

d. To halt an ACE, call the function ix_res_delete_ace. 

These functions and procedures are described in Chapter 2, “OMS Global 

Services API,” in the IXA SDK Reference. 



Chapter 5 

Controlling Packet Flow 

This chapter explains how packets flow into and out of an IXA application according 

to both the physical connections and the logical connections, known as bindings. It 

describes the physical network interfaces, the system and default targets to which 

you can direct packets, and how to create additional targets. 


l “Defining Packet Flow” on page 47 

l “Binding Targets as Packet Destinations” on page 48 

l “Defining Additional Targets” on page 50 

l “Directing Packets to a Target” on page 51 

l “Using Targets for Packet Processing” on page 51 

l “Receiving and Transmitting on Network Interface Ports” on page 53 

Defining Packet Flow 

Physically, packets flow into an IXP1200 system through network interfaces (ports), 

and back out through the same or other ports. Logically, packets move through an 

IXA application from one ACE to another. ACEs are the software entities that receive 

and dispose of packets. 

The system defines ACEs that communicate directly with the ports. These interface 

ACEs get packets from ports and send them to application ACEs, and receive packets 

from application ACEs to send out over ports. The application ACEs act on the 

packets while they are in the IXP1200 system. 

Typically several ACEs act on packets, at least to transport them to and from the 

ports. You determine the path that packets take through your application’s ACEs by 

binding the ACEs together in the order in which packets should encounter them. 


Controlling Packet Flow 47

Binding Targets as Packet Destinations 

Physical 

Packet Flow 

Each IXP1200 system has several physical network interfaces or ports. Depending on 

the board configuration, these can be connected directly to the network or to other 

packet sources and destinations, such as other IXP1200 boards. The quantity and type 

of ports also depends on the board configuration. For example, the IXDP1200 

Advanced Development Platform has sixteen fast Ethernet (10/100BaseT) ports and 

two gigabit Ethernet ports. 

Logical Packet 

Flow 

The ACE model of packet handling requires that packets be passed among ACEs in 

an IXA application. Therefore, each physical interface is represented in software by a 

special-purpose system ACE called an interface ACE. (These are described in more 

detail in a later section, “Receiving and Transmitting on Network Interface Ports” on 

page 53.) 

The IXA SDK includes system-defined ACEs for each of the network interfaces in the 

IXDP1200 Advanced Development Platform, and for the Linux * TCP/IP stack. The 

quantity, types, and names of system ACEs depend on the physical configuration of 

the IXP1200 system. Your customized system startup script loads and starts system 

ACEs for each of the ports your application uses. 

The interface ACEs act as software packet sources and destinations for the application. 

Packets flow through an IXP1200 system from a port through an interface ACE 

to one or more application ACEs, and out through an interface ACE to a port, as 

shown in the following figure: 

Input interface ACE Applications and modules Output interface ACE 

Packet flow 

match: act on 

? 

not 

match 

? 

not 

Drop 

The connections between ACEs that determine how packets flow are called bindings. 

The API provides the tools for you to bind ACEs together. Packets flow through an 

IXP1200 system only after you have created bindings. 


In an ACE, packets flow in only one direction: through the ACE to a target within the 

ACE. A target provides a way to connect an ACE to a destination for packets. Each 

ACE can have multiple targets. 

The manager program for the application, which creates the ACEs, can also determine 

the packet flow by binding targets to other ACEs. 

l 

For a packet to flow into an ACE, the application must bind the target in the 

packet’s source ACE to that ACE. 

48 Controlling Packet Flow 



l 

For a packet to flow out of an ACE, the application must: 

a. Create a target as part of the ACE (in the ACE initialization code). 

b. Bind the target to a destination ACE, using the function ix_res_bind in the 

manager program that creates the ACE, or using a command-line utility. 

c. Direct the packet to the target in an action function in the ACE action code. 

This means that every source that sends packets must be represented by an ACE that 

contains a target, and every destination must be represented by an ACE. A packet 

source or destination can be, for example, another ACE in the same application, an 

ACE in a different application, or a network interface or protocol stack, represented 

by a system ACE. 

ACE A 

Packet flow 

rule match: action 

no match: action 

Target 1 

Output interface ACE 

Target 2 

Targets bound to interface ACE 

Target bound to ACE B 

ACE B 

action 

Target 3 

Binding 

Targets and 


Targets are represented in your action code by ix_target structures. Each ACE is 

automatically initialized with the default target object named default. You can 

create additional targets; see “Defining Additional Targets” on page 50. 

All targets, including the predefined targets, are initially unbound. You must bind an 

ACE’s targets before packets can flow. In a simple application, you bind the default 

target to the next ACE in the normal flow of traffic. 

You bind application ACEs to system ACEs to provide packet sources and destinations 

for your application. For example, to pass packets out to the network, bind the 

system-defined default target of MyAce to the output interface ACE, as follows: 

ix_res_bind (res_session, "/MyAce/default", "/ifaceOutput"); 

To receive packets from the network, bind the target of the input interface ACE. For 

example: 

ix_res_bind (res_session, "/ifaceInput/default", "/MyAce"); 

NOTE: 

For details on the naming of ACEs, targets, and system ACEs, see the IXA 

SDK Reference. 

In addition to the API function ix_res_bind, the IXA SDK provides utilities for 

binding that you can use from the command line or from a script. 

l 

The ixbind command binds a target to an ACE directly. 

Controlling Packet Flow 49 


Defining Additional Targets 

l 

The ixsh utility has a bind command that you can use as part of a series of ACE 

management commands. 

Typically, the startup script and configuration file determine the bindings for an 

application at startup. For details on these and other commands and utilities, see the 

IXA SDK Reference. 

Unbound 

Targets 

Some applications, such as monitors and most intrusion detection systems, do not 

forward packets. An ACE performing such a task simply discards the packets. 

Directing a packet to a target without binding the target to a destination ACE causes 

packets to be dropped, as shown in the following figure. 

ACE A 

Packet flow 



Target 1 


Target 2 

Targets bound to destinations 

ACE B 



Target 3 

Target 4 

Unbound target 

Dropped 

If you leave a target unbound, then direct packets to it, those packets are dropped. 

However, you can drop packets more efficiently by not directing them to a target at 

all, while still returning RULE_DONE from the final action function. See “Directing 

Packets to a Target” on page 51. 

Defining Additional Targets 

The set of targets in an ACE represents the set of all possible packet destinations in 

that ACE, across all actions. 

l 

l 

In a simple case, an ACE passes most packets to the default target bound to an 

egress interface or to the next processing ACE, and defines another target to pass 

exception-case packets to a control-module ACE for exception processing. 

An ACE that performs a demultiplexing function, for example, might have 

multiple outgoing targets for different types of packets. 

To create additional targets within your application ACEs, you must do the 

following: 

1. In the ix_init function that creates the ACE, allocate an ix_target structure. 

2. Create the target using the ix_target_init function. 

ix_error ix_init (int argc, char **argv, ix_ace **acep) 

{ 



Directing Packets to a Target 

//allocate ace and target, pass to init fns 

ix_ace myace; 

ix_target mytarget; 

} 

ix_ace_init (myace, argv[1]);//ACE name passed in 

ix_target_init (mytarget, myace, "MyTarget"); 

... 

Directing Packets to a Target 

Action functions in the ACE determine the path that a packet takes through an application 

by specifying whether the packet has completed processing and by directing 

the packet to a specific target. 

Packets are represented within action code by an ix_buffer object. 

An action function must: 

1. Use the function ix_target_take to direct the current packet buffer to the specified 

target, if processing is done. 

2. Return one of the following constant values to indicate whether rule processing 

should continue on this packet buffer: 

— RULE_DONE 

— RULE_CONT 

If all action functions specified by successful rules are executed and none of them 

returns RULE_DONE to indicate that it has disposed of the packet buffer, the buffer is 

passed to the ACE’s default target. 

For more information on writing action functions, see the following: 

l 

l 

Chapter 10, “Initializing and Acting on Packets in an ACE.” 

Chapter 3, “The ASL Core Primary Package API,” in the IXA SDK Reference 

Using Targets for Packet Processing 

An application can bind targets to several ACEs, possibly on different processors, in 

order to perform serial processing on packets, or to distribute packets to different 

routes. 

Serial Packet 

Flow 

The following figure illustrates a simple cascade of ACEs defined by their target 

bindings. 

Controlling Packet Flow 51 


Using Targets for Packet Processing 

Input interface ACE 

Target T1 

Bound target-to-ACE 

flow 


Packet-to-target 

flow 

Forwarder ACE 

In cache? 

Yes: forward 

No 

Target T3 

Target T2 


Update data; 

forward 

Target T4 

In this example: 

l 

Target T1 is in the system ACE that represents an input network interface. T1 is 

bound to the Forwarder ACE. This directs all incoming traffic to the Forwarder 

ACE, which handles basic fast-path processing. 

l The Forwarder ACE contains two targets, T2 and T3. Most traffic is directed to T2, 

which is bound to the system ACE for the output network interface. Exception 

cases are directed to target T3, which is bound to another ACE, called FwdControl. 

l 

The FwdControl ACE processes the exception-case packets that it receives from 

the Forwarder ACE, then directs them to its own target, T4. T4 is also bound to 

the system ACE for the output network interface, so the exception-case packets 

are inserted back into the traffic flow. 

Packet Flow 

Redirection 

Because packets are passed to targets, rather than directly to other ACEs, you can 

easily insert another operation into your application by adding another ACE and 

rebinding the targets. 

For example, you could add a Firewall ACE to decide whether or not to allow 

packets through the output interface. The following figure illustrates how you can 

insert this ACE without having to change the logic or code of the existing ACEs, 

simply by rebinding the targets T2 (in Forwarder) and T4 (in FwdControl) to the 

Firewall ACE. 



Receiving and Transmitting on Network Interface Ports 



Target T1 

Firewall ACE 

Yes 

No 

Packet OK? 

Target T5 

Target T6 

Drop 

Packet-to-target 

flow 

Forwarder ACE 

In cache? 

Yes: forward 

No 

Target T3 

Target T2 

Bound target-to-ACE 

flow 


Update data; 

forward 

Target T4 

In the example, the Firewall ACE’s target T5 is bound to the output network interface, 

allowing packets into traffic, and target T6 is unbound, allowing packets to be 

discarded. 


In the software, physical network interface ports are represented by a specialpurpose 

entity called an interface ACE. Interface ACEs are created and initialized at 

system startup, using a configuration script that you customize. You configure the 

startup scripts to load and start an input ACE and an output ACE, configuring them 

to receive and transmit on the ports you need, depending on both the physical configuration 

of the IXP1200 system and on how you plan to use it. For the IXDP1200 

Advanced Development Platform, the IXA SDK provides two types of ports, the fast 

Ethernet (10/100) ports and the gigabit Ethernet ports. The interface ACEs can 

handle both types of port. 

An interface ACE is a type of system ACE. A system ACE, unlike other ACEs, does 

not classify packets, but only transmits them. (The other type of system ACE, the stack 

ACE, represents a protocol stack.) However, it looks like an ACE to the OMS Name 

Server, which allows you to direct packets to and from the ports. 

System ACEs are implemented as microACEs—that is, they run partly on the 

IXP1200’s microengines, and partly on the core processor. 

l 

l 

The microengine pieces are called microblocks. The microblocks communicate 

directly with the hardware ports, assembling mpackets into packet buffers and 

disassembling them for transmission. 

The core component communicates with the microblocks, and with other ACEs. 

The input ACE exports a crosscall interface that other parts of your application 

can use to configure it. The output ACE does not require further configuration 

after installation. 


Controlling Packet Flow 53


The input interface ACE, like all ACEs, has a default target. You must bind the default 

target to the microACE containing the next microblock in the group. This is a static 

binding; that is, you cannot change it at run time. It reflects the processing pipeline 

on the microengine, which is part of compiled code and cannot change at run time. 

You can create a static binding in either of the following ways: 

l 

l 

Programmatically, use the Resource Manager function RmBindMicroAce, rather 

than the Resolver function ix_res_bind. 

In the configuration file for the startup script, use the static flag for the bind utility. 

For example: 

bind static ifaceInput/default CountMicroAce2 

See Also 

l Chapter 6, “Writing MicroACEs” on page 55 

l Chapter 8, “Stack and Library ACEs” on page 87 

l The IXA SDK Reference 



Chapter 6 

Writing MicroACEs 

This chapter provides information on the architecture and design of microACEs, 

which make use of the Intel ® IXP1200’s microengines for fast-path processing. It 

contains the following topics: 


l “MicroACE Architectural Elements” on page 56 

l “Loading MicroACEs” on page 58 

l “Writing the Core Component of a MicroACE” on page 61 

l “Configuring MicroACEs with Crosscalls” on page 68 

l “Microblock Types and Groups” on page 68 

l “Writing a Dispatch Loop” on page 71 

l “Writing a Microblock” on page 75 

l “MicroACE Design Example” on page 77 

Overview 

The microACE programming model allows a packet-processing application to make 

use of the IXP1200’s microengines for acceleration of fast-path processing. 

MicroACEs perform specific tasks such as IP forwarding, network address translation 

(NAT), and IP filtering. 

A microACE has two logical components, running on different processors: 

l 

A microblock contains fast-path packet processing logic which you write in microcode 

to run on a microengine. Microblocks can be one of three types: 

— Source microblocks receive packet buffers from outside the microengine. 

— Transform microblocks operate on packet buffers and pass them on to other 

microblocks. 

Writing MicroACEs 55 


MicroACE Architectural Elements 

l 

— Sink microblocks send packet buffers out of the microengine. 

Each microblock is associated with a core component, which you write in C/C++ 

and NCL to run on the core processor. The core component is a complete ACE 

with additional elements that initialize and manage the microblock component. 

Interface ACEs are implemented as microACEs with source (Rx) and sink (Tx) 

microblocks. You use the interface microACEs to receive and transmit packets 

through the network interface ports. 

You typically combine microACEs with conventional ACEs in an application. You 

can combine the interface microACEs with microACE building blocks that are 

provided by Intel, that you write yourself, or that are provided by third parties. The 

IXA SDK provides source files for sample applications that use the system and library 

ACEs in various configurations, in the following location: 


To develop microcode and build microcode images, use the IXP1200 Microengine 

Development Environment. The source files for the microACEs and dispatch loop 

that form a microcode image are collected into a single project file with the extension 

.dwp. For information on using the microengine development tools and microcode 

reference information, see the IXP1200 documentation set. 


A microACE combines a core component, which runs on the core processor, with a 

microblock, written in microcode to run on a microengine. 

l 

l 

l 

l 

l 

A management program loads and configures microACEs along with the conventional 

ACEs for an application. 

The management program initializes the microACE Resource Manager, which 

deals with resource allocation, packet demultiplexing, and other system-level 

microengine management problems. 

Several microblocks are typically combined into a single microengine image 

called a microblock group. Each of the microblocks in a group is associated with 

exactly one core component. 

A microcode dispatch loop for each microengine initializes the microblocks in a 

group and determines how packets flow into, among, and out of the microblocks. 

The management program creates static binding among the microACEs to match 

the packet flow among microblocks in each group, as determined by the dispatch 

loop. Together, the microblock group and their linked core components form a 

microACE group. 

56 Writing MicroACEs 



Architecture 

Summary 

The following table provides a brief description of each element in the microACE 

architecture. The remaining sections of this chapter go into more detail on each of the 

elements. 

Element 

Management program 

Resource Manager 

Core component 

Microblock 

Microblock group 

Description 

A part of your application written in C/C++ that starts the 

microACEs along with the conventional ACEs for an application, 

performing all necessary configuration. Either a management 

program or a startup script must initialize ACEs, 

load and start the microcode images on the microengines, 

and set up microACE bindings to match the way that the dispatch 

loop has configured the processing sequence in each 


System software that provides a set of resources for the ACE 

and microACE management program to use in managing the 

microengine memory and shared state. Also provides the 

run-time component for handling exception processing. 

An ACE, written in C/C++ and NCL, that manages a microblock 

in addition to classifying and acting on packets. 

The ACE maintains shared state between itself and its associated 

microblock. It acts as a crosscall server and exports a 

crosscall interface for management of the microblock. 

The core component receives exception packets from its 

microblock, processes them, and sends them to the appropriate 

targets. The core component can also receive packets 

from other ACEs whose targets are bound to it and send them 

down to its microblock for processing. 

The core component of a microACE must always have one 

static target bound to the microACE containing the next 

microblock in the dispatch loop’s processing sequence. 

A microcode macro that provides the acceleration component 

of a microACE. Typically processes the most common cases 

of packet forwarding and passes exception case packets to 

the core component for further processing. 

A microblock can act as a packet source or sink, or it can 

transform packets. 

One or more microblocks that have been combined into a single 

microengine image. 

When you compile a microblock group, the microcode 

assembler produces an image file with the extension.uof. 

The management program loads this image onto a specific 

microengine during initialization. 

This allows several stages of processing to occur on a single 

microengine. Typically all threads on the microengine execute 

the same microblock group. You can load the same 

microblock group on more than one microengine. 



Loading MicroACEs 

Element 

Dispatch loop 

Description 

For each microblock group, you write a microcode dispatch 

loop to implement the packet flow within the group. The dispatch 

loop configures the microblocks in the group into a processing 

pipeline. 

The loop for each microblock group starts with a packet 

source microblock, ends with a packet sink, and can have one 

or more transform microblocks in between. 

Microcode image 

The compiled single object (.uof file) that contains the 

microblocks in a group and the dispatch loop that defines the 

processing pipeline. 


The management program for an application or a startup script must load and start 

the ACEs and set target bindings. In addition, to load and start microACEs (including 

the interface ACEs), the management program or script must do the following: 

1. Initialize the Resource Manager using the function RmInit. An application must 

do this once before making any other calls to the Resource Manager. The Resource 

Manager initializes the hardware. 

2. Configure the ports using the function RmSetPortConfig, passing information on 

which ports need to be enabled. 

You can examine the port configuration that the Resource Manager sets up using 

RmUengGetConfig. You can use RmUengSetConfig instead of RmSetPortConfig 

to configure each microengine individually, or to change the configuration. 

3. Use the function RmUengSetUcode to write each compiled microcode image to the 

Resource Manager before launching the microACEs. An image is a .uof file 

containing the microblock group and dispatch loop for one microengine. 

4. Launch the microACEs using the function RmCreateMicroAce. Like 

ix_res_create_ace, this function calls the ACE’s initialization function, 

ix_init. Each microACE’s initialization routine must: 

a. Register with the Resource Manager using the function RmRegister. 

a. Patch variables into the microcode image using the function RmUengPatch- 

Symbols. 

b. Create at least one target to be statically bound to the microACE containing the 

next microblock in the group. 

5. Bind static targets among the microACEs to match the dispatch loop’s processing 

pipeline, using the function RmBindMicroAce. 

6. Bind any conventional targets among the microACEs and other ACEs using the 

Resolver function ix_res_bind. 

7. After launching the microACEs, load the microcode images for each microengine 

using the function RmUengLoad. 




8. Start the microACE code running on each microengine using the function RmUengEnable. 

9. Configure the microACEs using their startup scripts or crosscalls. 

For more information on startup scripts and configuration files, see Chapter 4, 

“Configuring and Starting IXA Systems.” 

For a complete description of the Resource Manager and Resolver API functions, see 

the IXA SDK Reference. 

Setting Up a 

Processing 

Pipeline for 

MicroACEs 

The microblocks in a single image (a microblock group) form a packet-processing 

pipeline on a microengine. Packets come in through the input media interfaces, are 

processed by a series of microblocks, and are sent out through the output media interfaces, 

or on to another microblock group on another microengine. 

The dispatch loop’s microcode defines the packet flow among the microblocks in a 

group. The packet flow is fixed when you compile the microblocks and dispatch loop 

to generate a .uof microcode image. You cannot change the packet flow at run time. 

After processing a packet, a microblock returns a value to the dispatch loop. The 

dispatch loop uses the returned value to determine the disposition of the current 

packet. The microblock can tell the loop to send packets to: 

l 

l 

l 

The next microblock in the group 

Its own core component on the core processor 

Another microblock group 

port 

microblock 

port 

microblock 

Packet flow 

microblock 

Microengine 

microblock 

microblock 

Microengine 




Creating Static Bindings 

For each microblock group, the management program must bind targets in the core 

components to correspond to the microblock packet flow implemented by the 

dispatch loop. Unlike the bindings of conventional targets and ACEs, you cannot 

change these bindings at run time; they are static. 

Core processor 

Static Resource Manager bindings 

core component a 

core component b 


port 

Packet flow in dispatch loop 

microblock a 

microblock b 

Microengine 

port 

A special Resource Manager function, RMBindMicroAce, creates the static bindings. 

Like the Resolver function ix_res_bind, this function requires an open Resolver 

session. The system does not provide any special target for the static binding; you can 

create a target for this purpose, or you can use the default target. For example, if you 

create a target named static in microACE a as shown in the figure, create the static 

binding to microACE b in the ixsys.config system configuration file: 

bind static a/static b 

If you write your own startup management program, use the Resource Manager 

function: 

RMBindMicroAce (myResolverSession, "/a/static", "/b"); 

You can create additional targets in the microACE, bind them to other conventional 

ACEs or microACEs, and send packets to those targets. Similarly, you can bind 

targets in other ACEs to the microACE so that it can receive packets from them. 

Example 

The following pseudocode example of an ACE management program loads 

microACEs as well as conventional ACEs for an application, and sets their bindings, 

using Resource Manager API calls. 

int main(int argc, char**argv) 

{ 

// Initialize the Resource Manager 

RmInit(...); 

// Set the port configuration 

RmSetPortConfig(...); 

// Set the microcode image onto each microengine 

for (i = 0; i < MAX_NUM_UENG; i++) 

RmUengSetUcode(...); 



Writing the Core Component of a MicroACE 

// Launch microACES. This call is synchronous; by the time it 

// returns, the ix_init() of the microACE has been called. The // 

program assumes that all imported variables 

// were patched in by ix_init() 

for (i = 0; i < numberOfMicroaces; i++) 

RmCreateMicroAce(...); 

// Launch conventional ACES 

for (i = 0; i < numberOfRegularAces; i++) 

ix_res_create_ace(...); 

// Configure the microACEs and ACEs with crosscalls 

ConfigureACEs(...) 

// bind the microACEs together with static targets 

for (i = 0; i < numberOfStaticBinds; i++) 

RmBindMicroAce(...); 

// bind microACEs and other ACEs with regular targets 

for (i = 0; i < numberOfRegularBinds; i++) 

ix_res_bind(...); 

// Load the microcode 

RmUengLoad(...); 

// Enable the microengines 

RmUengEnable(...); 

// Loop forever 

while (1); 

} 


The core component runs on the core processor, and performs the following functions 

for the microACE: 

l 

l 

l 

l 

l 

l 

Exports IXA IDL interfaces to allow applications to configure the microACE. 

Allocates and sets up an SRAM control block to communicate with its associated 

microblock running on the microengines. 

Allocates and sets up tables and other data structures used by its associated 

microblock. 

Binds (patches) imported variables in the microcode to appropriate values during 

initialization. 

Receives exception packets from its associated microblock and processes them 

like a conventional ACE, using NCL and ASL. 

Handles packets received from other ACEs, sending them to its associated 

microblock on the microengines or to other targets. 

Like a conventional ACE, the C source code for the core component of a microACE 

must define an initialization routine, ix_init, and a termination routine, ix_fini. 

See “Initializing a MicroACE” on page 62 and “Terminating a MicroACE” on 

page 64. 


Writing MicroACEs 61


A microACE can contain conventional targets and the application can bind them to 

other ACEs or microACEs in order to pass packets to them. Similarly, an application 

can bind another ACE’s target to the microACE in order to send it packets. Like 

conventional ACEs, microACEs can use the default action function, 

ix_action_default, to handle packets by sending them to the default target. 

Exception 

Packet 

Handling 

The core component of a microACE handles exception packets that the microblock 

cannot process, using an application-defined exception handler. 

During the processing of a packet buffer, an exceptional condition might occur that 

requires additional processing. In this case, the microblock sends the buffer to its core 

processor core component by returning the special value IX_EXCEPTION to the 

dispatch loop. It passes an additional application-defined code along with the packet 

buffer to indicate what type of exception occurred. 

When the exception occurs, the dispatch loop places the buffer into a queue going to 

the core processor. All microblocks in a group share the queue. To identify the 

microACE that flagged the exception and will handle it, the dispatch loop uses the 

ACE tag, which is assigned by the RmRegister function when you initialize and start 

the microACE. The ACE tag has the form microblockName_TAG. After it has set the 

ACE tag, the dispatch loop can use the macro DL_SASink to send the packet up. 

The C source code for the core component of a microACE must define a handler 

routine for exception packets received from the associated microblock. See “Writing 

an Exception Packet Handler” on page 64. 

Initializing a 


A management program launches a microACE using the Resource Manager function 

RmCreateMicroAce, which is similar to the Resolver function for creating conventional 

ACEs, ix_res_create_ace. Like the Resolver function, it requires an active 

Resolver session. See the IXA SDK Reference for details of these functions. 

Like conventional ACEs, the core component of a microACE must define an initialization 

routine, ix_init. When you launch the microACE, the creation function calls 

the ix_init function that is defined in the source code specified for the new 

microACE. The creation function passes down command-line arguments to ix_init. 

MicroACEs must use the following convention for command-line arguments: 

Argument Description 

argv[0] 

Name of the executable. 

argv[1] Name of the ACE. 

argv[2] 

A bit mask indicating the microengines on which the microblock for this 

ACE runs. The 6 least significant bits of the microengine mask are used. 

The microengines are numbered 0-5. 

In addition to those things that it does for a conventional ACE (creating the ix_ace 

structure, calling ix_ace_init, creating related structures such as targets and sets, 

and initializing the ACE as a crosscall server and/or client), the ix_init initialization 

routine for a microACE must do the following: 




l 

l 

l 

Register the new microACE with the Resource Manager using the function 

RmRegister. This assigns the ACE tag that associates the microblock with the core 

component. 

Patch any imported variables for this microACE into the microblock, using the 

function RmUengPatchSymbols. After the microACE initialization routine returns, 

no more symbols can be patched. Symbols must be patched for all microACEs 

before the management program can load and start the microcode image. 

Use the Resource Manager to allocate memory in SRAM for the control block, and 

other shared memory (SRAM, SDRAM, or scratch) for any data structures to be 

shared with the microengines. See “Allocating Memory for Shared Data” on 

page 65. 

Initialization Example 

The following is a pseudocode example of a microACE initialization routine. 

ix_error ix_init (int argc, char** argv, ix_ace **acepp) 

{ 

// Allocate ACE structure, get ACE name and initialize ACE 

*acepp = malloc(...) 

name = argv[1] 

ix_ace_init(*acepp, name) 

// Initialize the Resource Manager 

RmInit(...) 

// Allocate SRAM for control block 

controlBlock = RmMalloc(...) 

// Allocate SRAM/SDRAM/SCRATCH for other data structures 

otherMemory = RmMalloc(...) 

// Set up these data structures 

SetupDataStructures(...) 

// Register an exception handler with the Resource Manager 

// and get a unique tag for the microblock. This tag can be used 

// to sendpackets to the microblock 

RmRegister(...) 

// Get the microengine mask for this ACE 

meMask = atoi(argv[2]) 

// For each microengine in the mask, patch variables 

// for this ACE 

for (i = 0; i < numberOfImportedVariables; i++) 

RmUengpatchSymbol(...) 

// Other ACE-specific actions, such as creating targets 

return 0; 

} 




Terminating a 


Like conventional ACEs, the core component of a microACE must define an termination 

routine, ix_fini. When an application stops a microACE, the Resource Manager 

calls the ix_fini function defined in that ACE’s executable. See the IXA SDK Reference 

for details of the ix_fini function. 

In addition to those actions it takes for a conventional ACE (calling the ix_ace_fini 

function and freeing the memory allocated for the ix_ace structure), the ix_fini 

function for a microACE must do the following: 

l 

l 

Unregister from the Resource Manager 

Free all allocated Resource Manager memory 

Termination Example 

The following is a pseudocode example of a microACE termination routine: 

ix_error ix_fini (int argc, char**argv, ix_ace *acep) 

{ 

// Unregister from the Resource Manager 

RmUnRegister(...) 

// Free all Resource Manager memory 

RmFree(...) 

// Terminate the path to the Resource Manager 

RmTerm(...) 

// Call the ix_ace_fini() function 

ix_ace_fini(...) 

// Free ACE structure and other memory allocated in ix_init 

free(...) 

} 

Writing an 

Exception 

Packet Handler 

The core component of a microACE typically defines a routine to handle exception 

packets received from the microblock. 

l 

l 

When you register the microACE during initialization using the Resource 

Manager function RmRegister, pass a pointer to the exception handler function, 

which you define in the C/C++ source code for the ACE. 

The Resource Manager calls the designated exception handler function once for 

every exception packet that the microblock identifies. 

Each exception packet the microblock sends up is associated with an exception code 

to indicate the reason for the exception. The exception handler must call the Resource 

Manager function RmGetExceptionCode to retrieve this exception code. Your application 

defines the exception codes and their meanings. 

The handler routine typically processes the packet and disposes of it. It can: 

l 

Send it back to the microblock for further processing using the Resource Manager 

function RmSend. 




l 

l 

l 

Send it to another ACE through a conventional target. 

Send it to another microACE through a static target; in this case, the packet is 

received by the core component of the microACE, which will send the packet 

buffer down to its associated microblock for processing. By convention, you do 

not send a packet buffer directly to the microblock of another microACE. 

Discard the packet and free the packet buffer. 

Exception Packet Handler Example 

The following is a pseudocode example of an exception handling routine: 

int ExceptionPacketHandler (void *ctxp, 

ix_ring ring, 

ix_buffer buffer) 

{ 

ix_ace* acep = (ix_ace*) ctxp; 

// Get the exception code for this packet. 

RmGetExceptionCode(...) 

// Process the packet and either send it to a target, 

// drop it, or use RmSend to send it back to the microblock 

... 

return 0; 

} 

Allocating 

Memory for 

Shared Data 

The microengines and core processor share access to three types and areas of 

memory: 

l 

l 

l 

uncached SDRAM 

SRAM 

cache memory (also called scratch memory) 

Some of the shared memory is used by the IXA system software and operating 

system, but a portion of it is available to microACEs through the Resource Manager. 

ASL (16 Mb) 


(48 Mb) 

Shared memory for the IXP1200 Evaluation Platform 

Linux (64 Mb) 

SDRAM 

ASL (1 Mb) 


(3 Mb) 

SRAM 


(4 Kb) 

Scratch 




While conventional ACEs define sets and searches to access application data, the 

microengines cannot access sets. If a microACE must store and access data, it must 

allocate a table in shared memory. The Resource Manager API provides a simple 

memory management mechanism, which you use for coarse-grained static allocation. 

Use the operating system to do fine-grained, dynamic memory management 

within the core component. 

Use the following Resource Manager API functions to manage memory for 

microACE data structures that the core component shares with the microblock: 

Function 

RmMalloc 

RmFree 

RmRead 

RmWrite 

RmGetPhysOffset 

RmGetBufferPtr 

RmGetMemInfo 

Description 

Allocates memory of a particular type (SDRAM, SRAM, or 

scratch) for the Resource Manager. 

Frees memory of a particular type in Resource Manager 

memory. 

Reads memory allocated by RmMalloc. 

Writes to memory allocated by RmMalloc. 

Retrieves the physical word offset from start of memory for a 

segment allocated by RmMalloc. 

Retrieves the buffer pointer for memory allocated by the 

RmMalloc function. 

Retrieves the free-memory statistics. 

For details of how to use these functions, see the IXA SDK Reference. 

Once the core component has set up and initialized data structures in shared memory, 

both the core component and microblock must define a mechanism for accessing the 

data. In the microblock, you can use the hardware hashing mechanism built into the 

IXP1200 network processor to hash into the data tables and reduce the search space. 

In order to duplicate these hash values in the core component, the ASL provides a set 

of hash functions that use the same hashing algorithm. For details of the ASL hash 

functions, see the IXA SDK Reference. 

Shared 

Memory Table 

Example 

The following example shows both sides (microengine and core processor) of how 

you might allocate a table in shared memory and access it with hash values. 

Microcode Side: Hash Initialization and Table Implementation 

/* Setting up Hash Table */ 

mul = MULT ; 

ECK(ix_hash64_init(&h64)) ; 

ECK(ix_hash64_set_mult(&h64, mul)) ; 

/* Microblock Table Implementation */ 

#macro calculate_hash[key, ipsrc, ipdst, sport, dport, proto] 

.local $hash0 $hash1 $hash2 $hash3 $hash4 tmp 

.xfer_order $hash0 $hash1 $hash2 $hash3 




; Setup the hash unit 

; 

immed[$hash4, MULT] 

csr[write, $hash4, hash_multiplier_64_lo], ctx_swap 

; setup the hash keys 

move[$hash0, sport] 

ld_field[$hash0, 1100, proto, protocol, tuple->dest_port, 

tuple->dest_add ) ; 

combined_key = key1 ^ key2 ; 

Index = TABLE_MASK ; 

Index = combined_key & TABLE_MASK; 

return Index ; 



Configuring MicroACEs with Crosscalls 

} 

ix_64bit hash_64( ix_16bit protocol, ix_16bit port, 

ix_32bit address ) 

{ 

ix_64bit val, key ; 

val = 0 ; 

key = ((ix_64bit)address) | (((ix_64bit)port)

Microblock Types and Groups 

You write a microblock as a microcode macro. Each microblock makes use of the 

dispatch loop global variables and macros to pass packet buffers and information. 

See “Writing a Dispatch Loop” on page 71. 

Packet buffers generally flow into the microblock group from a network interface 

port. A core component can also send packets down to its own microblock—the 

dispatch loop handles packets that come from the core components, steering them to 

the appropriate microblock. 

A microblock can send packets to the core component of its microACE, or to other 

microblocks in the group by returning values to the dispatch loop. The dispatch loop 

acts on the return values to define the flow of packets within and out of the group. 

Microblock 

Types 

There are three types of microblocks: 

l 

l 

l 

Source microblocks get the packets to be processed by the rest of the pipeline. 

Examples of source microblocks include those that read data from network interface 

ports or those that schedule packets for transmission from a set of queues. 

Transform microblocks process a packet and pass it to the next microblock. Transform 

microblocks can modify the buffer data, gather statistics on the buffer 

contents, or steer the buffer between multiple code blocks. 

Sink microblocks dispose of packets within the microblock group. Disposal 

actions can include queuing packets to another microblock or to the core component 

for further processing or transmitting the packet on a network interface port. 

Source Microblocks 

Source microblocks are responsible for obtaining the next packet buffer to be 

processed. The first microblock to run in a microblock group is the source microblock. 

Implement each source microblock as a macro with the following format: 

source_block [] 

The source microblock must do the following: 

1. Set the global variable dl_buffer_handle to a valid handle, or to 

IX_BUFFER_NULL if there is no buffer to process. 

2. Set the buffer length, buffer offset, and the input port variables using the dispatch 

loop macros. See “Defining Additional Global Registers” on page 73. 

3. If desired, set the receive status flags and the IXP1200 fast port sequence number 

if the buffer was received from a fast port. 

The microblock of an input interface microACE is an example of a source microblock. 

This code removes mpackets (the internal unit of transfer) from the IX Bus and reassembles 

them into a packet buffer. If the current mpacket completes a frame, the code 

returns the pointer to the completed buffer. If the frame is not complete, it returns 

IX_BUFFER_NULL. 

An application-defined source microblock would get the next packet buffer from the 

queue where it was passed from another microblock group, and set the buffer handle 

to point to it. If no packet buffers are in the queue, it returns IX_BUFFER_NULL. 



Microblock Types and Groups 

Transform Microblocks 

Transform microblocks perform basic packet operations. Some typical operations 

include IP forwarding, NAT, and filtering. The transform microblock operates on the 

packet buffer and returns an indication of how the packet buffer should be processed 

next. Any number of transform microblocks can run between the source and sink 

microblocks in a microblock group. Implement each transform microblock as a macro 

with the following format: 

transform_block [] 

The transform microblock must do the following: 

1. Get the current packet buffer handle from the dispatch loop global variable 

dl_buffer_handle. 

2. Process the packet buffer. 

3. Set the value of the global variable dl_next_block to tell the dispatch loop where 

to send the packet buffer next. 

— For fast-path processing, set the variable to the number of the next microblock 

in the group. Your application defines the microblock numbers. 

— For exception cases, set the variable to IX_EXCEPTION to send the buffer to the 

transform microblock’s core component. You can pass an exception code with 

the packet using the dispatch loop macros. 

The microblocks of the library ACEs are examples of transform microblocks. 

Sink Microblocks 

Sink microblocks are responsible for disposing of packet buffers. The last microblock 

executed in a microblock group for a given packet buffer is a sink microblock. Implement 

each sink microblock as a macro with the following format: 

sink_block[] 

The sink microblock must do the following: 

1. Get the handle to the current packet buffer from the global dispatch loop variable 

dl_buffer_handle. 

2. If desired, use the dispatch loop macros to get the output port number for the 

buffer being processed. 

The microblock of an output interface microACE is an example of a sink microblock. 

This code disassembles a packet buffer into mpackets (the internal unit of transfer) 

for transmission through a network interface port. 

An application-defined sink microblock would queue the packet buffer for 

processing by another microblock group. 

Examples of 

Microblocks 

Typical microblocks for microACEs can include the following: 



Writing a Dispatch Loop 

Block Type Description 

Slow Ethernet 

Ingress 

Fast Ethernet 

Ingress 

source 

source 

Reads mpackets from the IX bus and reassembles 

them into a packet buffer. When it has a complete 

buffer, it returns the handle for further processing. It 

can perform link-level filtering as appropriate. 

This microblock is used by the input interface ACE 

for this type of port. 

Similar to the Slow Ethernet Ingress, but handles 

the fast (gigabit) Ethernet ports. 

This microblock is used by the input interface ACE 


IP Forward transform Performs the destination route lookup and the modifications 

needed for forwarding the buffer. 

Flow Processor transform Processes packets based on a set of tables, using 

the 5-tuple that identifies each TCP/UDP connection. 

Provides filtering and NAT. 

Sink Packet sink Queues packets to be processed by another 


Slow Ethernet 

Transmit 

Fast Ethernet 

Transmit 

sink 

sink 

Transmits packet buffers out slow (10/100) Ethernet 

ports. 

This microblock is used by the output interface ACE 


Transmits packet buffers out fast (gigabit) Ethernet 

ports. 

This microblock is used by the output interface ACE 



The packet flow within a microblock group is defined by the microcode dispatch loop 

that you provide. You link the dispatch loop with the microblocks in the group to 

compile the microcode image (.uof file) for each microblock group. 

l 

l 

l 

The dispatch loop first initializes each microblock in the group, then handles 

packets that have been sent down from the core components on the core 

processor, passing them to the proper associated microblocks. 

The dispatch loop caches common variables in registers that the microblocks can 

access either directly or using a set of predefined helper macros. 

The main portion of the dispatch loop describes the packet flow among the 

microACEs that are part of the microblock group. 




Microblocks in the group return values to the dispatch loop by setting the global variables. 

The dispatch loop acts on the return values to define the flow of packets within 

and out of the group. 

The dispatch loop can use system-defined macros to transfer packets to and from the 

core processor, to send packets to a different microblock group, to access global variables, 

and to manipulate packet buffers. The predefined macros are listed and 

described in Chapter 6, “MicroACE Support Services,” of the IXA SDK Reference. 

Dispatch Loop 

Global 

Registers 

Each microblock directly sets and accesses the following global registers, which the 

dispatch loop can also access: 

Global Register 

Description 

dl_buffer_handle 

dl_next_block 

Stores a buffer handle for the current packet buffer. 

The source microblock at the top of the dispatch loop must 

set this register to a valid buffer handle or to 

IX_BUFFER_NULL. 

Stores the microblock return value. 

l To steer the packet buffer to the appropriate next transform 

microblock for processing, each transform microblock 

sets this register to the destination microblock’s 

application-defined number. 

l To send a packet buffer to the core component on the 

core processor, the transform microblock sets this register 

to IX_EXCEPTION. 

The dispatch loop caches commonly used variables such as thread ID, input and 

output port, and so on, in global registers. You must use a .local statement at the 

top of the dispatch loop to define the global registers for the buffer handle and return 

value, and any other registers that will be used by any microblock. For example: 

.local dl_buffer_handle dl_next_block dl_reg1 dl_reg2 dl_reg3 

The dispatch loop and microblocks can use a set of predefined helper macros to set 

and retrieve values from these registers, and to create and manipulate packet buffers. 

To use these, include the file: 

SDKinstallpath/src/microace/common/dispatchloops/ 

DispatchLoop_h.uc 

The predefined macros are listed and described in detail in Chapter 6, “MicroACE 

Support Services,” of the IXA SDK Reference. 




Defining Additional Global Registers 

Depending on register availability, a dispatch loop can define global registers for the 

use of a particular transform microblock, which are saved across iterations of the 

dispatch loop. The names of global registers that you define for a particular microblock 

must be prefixed with the name of that microblock, in the form 

blockName_regName—for example, wred_averageQueueSize. 

All other registers used by a microblock must be declared as .local within the 

microblock, as well as in the dispatch loop. 

Implementing 

Control Flow 

Each microblock sets the dl_next_block register, returning a numeric value that 

indicates which path a packet buffer should follow, or IX_EXCEPTION. (See 

“Returning Values to the Dispatch Loop” on page 75.) The dispatch loop checks the 

dl_next_block register and interprets the value. For example: 

IPFilter#: 

IPFilter[ ] 

.if (dl_next_block == 1) 

br[DL_MESink#] 

.else 

br[DL_Drop#] 

.endif 

The dispatch loop uses this mechanism to determine the sequence in which 

microACEs process packets. Because this sequence is compiled into the microcode 

image, it cannot be changed at run time. Your application must set up static target 

bindings for the microACEs to match the processing sequence in the dispatch loop. 

For more information, see Chapter 4, “Configuring and Starting IXA Systems,” and 

Chapter 5, “Controlling Packet Flow.” 

Dispatch Loop 

Example 

The following example shows a typical structure for a dispatch loop. 

The dispatch loop begins by declaring all the registers that will be used by the loop 

itself and by the microblocks for shared variables. The #include statements identify 

each microblock in the group. 

; declare global variables 

.local dl_buffer_handle dl_next_block dl_reg1 dl_reg2 dl_reg3 

; Include microblock source files 

#include "EthernetIngress.uc" 

#include "IPFilter.uc" 

#include "IPFwd.uc" 

The dispatch loop initializes each microblock in the group by calling the 

BlockName_Init[] macro. 

; Do initialization 

DL_Init[ ] 

EthernetIngress_Init[ ] 

IPFilter_Init[ ] 

IPFwd_Init[ ] 




The first part of the dispatch loop dequeues packets coming from the core processor, 

passing them directly to the destination microblock. 

; Run the dispatch loop 

.while(1) 

; Consume packets from the SA. 

DL_SASource[ ] 

.if (dl_buffer_handle == IX_BUFFER_NULL) 

br[Main_Dispatch#] 

.elif (dl_next_block == IPFILTER_TAG) 

br[IPFilter#] 

.elif (dl_next_block == IPFWD_TAG) 

br[IPFwd#] 

.endif 

In this example, the dispatch loop has an Ethernet interface source microblock, 

followed by IPFilter and IPFwd transform microblocks. The microblocks return 

value by setting dl_next_block to indicate where to pass the packet next. 

; Main dispatch loop 

Main_Dispatch#: 

EthernetIngress[ ] 

.if (dl_buffer_handle == IX_BUFFER_NULL) 

.continue 

.endif 

.if (dl_next_block != 1) 

br[DL_Drop#] 

.else 

IPFilter#: 

IPFilter[ ] 

.if (dl_next_block == IX_EXCEPTION) 

.local ace_tag 

immed[ace_tag, IPFILTER_TAG] 

DL_SetAceTag[ace_tag] 

.endlocal 

br[DL_SASink#] 

.elif (dl_next_block == 1) 

IPFwd#: 

IPFwd[ ] 



immed[ace_tag, IPFWD_TAG] 


.endlocal 




.else 

br[DL_Drop#] 

.endif 

.else 

br[DL_Drop#] 

.endif 

.endif 



Writing a Microblock 

DL_SASink#: 

DL_SASink[ ] 

.continue 

DL_MESink#: 

DL_MESink[ ] 

.continue 

DL_Drop#: 

DL_Drop[ ] 

.endw 

.endlocal 


A transform microblock performs whatever classification or processing is necessary 

on the current packet buffer, which it finds and stores in a global register. It then 

returns an application-defined value in another global register, that the dispatch loop 

uses to determine the further disposition of the packet buffer. Typically, it either 

transmits the packet or flags an exception so that the packet will be processed by the 

core component. 

Returning 

Values to the 

Dispatch Loop 

Each microblock can have one or more logical outputs, and returns a numeric value 

that indicates which path a packet buffer should follow. A microblock identifies the 

next destination microblock by setting dl_next_block to an application-defined 

number or to IX_EXCEPTION. 

l 

The return value IX_EXCEPTION is reserved to indicate that the buffer should be 

sent to the core component on the core processor for further processing. 

l By convention, each microblock numbers its other logical outputs starting at 1. 

When you write a microblock for reuse, you must document: 

— The number of logical outputs it has 

— The return values assigned to the outputs 

— The semantic meaning associated with the outputs 

Transmitting a 

Packet 

To transmit the current packet after processing, the microblock must do the 

following: 

1. Determine which network interface port to use for transmission, according to the 

application logic. 

2. Use the DL_SetOutputPort macro to set the port number in the packet. 

3. Set the global register dl_next_block to the application-defined code for transmission. 

For example, the following lines set up a fast-path packet for output on the first 

gigabit Ethernet port: 




DL_SetOutputPort[16] 

immed[dl_next_block, 1] 

In this case, the dispatch loop must interpret the next-block value of 1 to mean that it 

should use the macro DL_MESink to transmit the packet. For example: 

.if (dl_next_block == 1) 


... 

DL_MESink#: 

DL_MESink[ ] 

.continue //return to top of dispatch loop 

The DL_MESink macro transfers the current packet to the microengine that is running 

a microcode image that contains an output interface ACE configured for the packet’s 

output port. 

Sending an 

Exception 

When an exception occurs, the transform microblock must do the following: 

1. Use the DL_SetExceptionCode macro to set the application-defined exception 

code 

2. Set the dl_next_block register to IX_EXCEPTION. 

The dispatch loop must do the following: 

1. Check for the next-block value of IX_EXCEPTION. 

2. Use the macro DL_SetAceTag to set the current ACE tag correctly for the microblock 

that flagged the exception. 

3. Use the macro DL_SASink to send the current packet buffer to the microACE’s 

core component (as identified by the ACE tag) for exception processing. 

The exception handler in the core component uses the Resource Manager function 

RmGetExceptionCode to retrieve the code set by the microblock. 

For example, the following lines from the L3 forwarder library ACE’s microblock set 

the exception code which that ACE defines for an ARP packet, then sets the exception 

flag in dl_next_block: 

immed32[exception_code, IPV4UNICASTFWD_EXCEPTION_ARP] 

DL_SetExceptionCode[exception_code] 

immed32[dl_next_block, IX_EXCEPTION] 

The following lines from a dispatch loop detect the exception state and send the 

exception packet to the core component of the L3Fwdr microACE: 

L3Fwdr#: 

L3Fwdr[ ] //sets exception code and flag 



immed[ace_tag, L3FWDR_TAG] 


.endlocal 




MicroACE Design Example 


DL_SASink#: 

DL_SASink[ ] 

.continue 


The following example shows how a layer 3 forwarding application uses microACEs. 

Core processor 

Stack ACE 

Input IF ACE 

configuration 

crosscalls 

L3Fwd 


Output IF ACE 


port 

Input IF 

microblock 

exception 

packets 

L3Fwd 

microblock 

Output IF 

microblock 

port 

Packet flow 

Microengine 

This application, like most applications, uses the system-defined interface ACEs for 

input and output of packet buffers from and to the network interface ports. The interface 

ACEs are implemented as microACEs, with a core component and a microblock 

that communicate through the Resource Manager. Applications can configure the 

interface ACEs using their exported crosscalls. 

The application also makes use of the system-defined stack ACE, which passes 

packet buffers to and from the Linux * TCP/IP stack. The stack ACE is a conventional 

ACE. 

The application logic is in the L3Fwd microACE. The microblock component handles 

fast-path processing, forwarding packets based on a forwarding table. It sends exception 

packets (in this case, those with IP options in the header, fragmented packets, 

ARP and so on), to its core component. 

The Resource Manager, a piece of system software running in the core processor 

kernel, passes configuration information and packet buffers between the core components 

of the microACEs and their associated microblocks. 

In addition to the ACEs and microACEs, the application includes: 

l A C management program that launches the microACEs and the stack ACE, 

binds them together, downloads microcode and enables the microengines. 




l 

A microcode dispatch loop for each microengine that implements the data flow 

for that microengine and caches commonly used variables in registers. The 

dispatch loop sends and receives packets to and from the core processor and the 

other microengines. 

During application initialization, the management program binds the static 

microACE targets to reflect the flow of data in the dispatch loop. Once bound, they 

cannot be changed. The targets between the microACEs and the stack ACE are 

conventional targets and can be bound and unbound more than once. 

Packets flow through this application as follows: 

l 

l 

l 

l 

l 

The microblock component of the input interface microACE gets a packet from a 

port. It sets the input port in a global register using a dispatch loop macro and 

passes all packets to the L3Fwd microblock. 

The L3Fwd microblock checks whether the packet is an IP packet, ARP packet, or 

some other type of packet. For every IP packet, the microblock validates the 

packet, dropping invalid packets. 

— If a packet is valid, but has options in the header, is fragmented, or is multicast 

it is considered an exception case and the microblock sends it to the L3Fwdr 

core component using the dispatch loop and the Resource Manager. 

— If a valid packet is not an exception case, the microblock finds the next-hop IP 

address and output port number in the forwarding table. It retrieves the destination 

MAC address of the next-hop IP and sets it for this packet. It then sets 

the output port number in a global register using a dispatch loop macro. 

The dispatch loop looks at the output port number in the global register and 

queues the valid, nonexception packet for output. There is one queue per port. 

The microblock for the output interface microACE dequeues the packet and sends 

it out over the appropriate port. 

For an exception packet, the L3Fwdr core component on the core processor 

processes the packet. It then takes one of the following actions: 

— Sends the packet to the output interface ACE using the conventional bound 

target. The core component of the interface ACE then sends the packet down 

to its own microblock using a Resource Manager call. 

— Sends the packet to the stack ACE, which processes the packet then sends it to 

the output interface ACE. 

— Sends the packet back down to its own microblock using the Resource 

Manager. 



Chapter 7 


This chapter describes the interface ACEs, system-defined microACEs that every 

application uses to receive and transmit packets for each network interface port. The 

chapter contains the following sections: 


l “Initializing Interface ACEs” on page 81 

l “The Input ACE” on page 83 

l “The Output ACE” on page 85 

Overview 

Interface ACEs are microACEs whose microblocks allows the microengines in the 

IXP1200 to communicate with the network interface ports. An IXP1200-based system 

must include the interface ACEs in order for the IXA application to receive and 

transmit traffic through any port. The interface ACEs can be configured to handle 

both 10/100BaseT Ethernet and gigabit Ethernet ports. 

The purpose of interface ACEs is to mask network interface details that are specific 

to particular hardware environments. These objects act as packet sources and destinations, 

and as drivers for the network interfaces. They are opaque to other ACEs. 

You can configure interface ACEs using their exported crosscall interfaces, but you 

cannot modify them. 

There are two types of interface ACE, input and output. 

l 

The input interface ACE, named by convention ifaceInput, is responsible for 

receiving packets from all of the physical ports. An input ACE contains a source 

microblock, which acts as a source of packet buffers for its microblock group. The 

input ACE passes received packets to the next microblock in the group. 


Interface ACEs 79

Overview 

l 

The output interface ACE, named by convention ifaceOutput, is responsible 

for transmitting packets on all of the physical ports. An output ACE 

contains a sink microblock, which consumes packet buffers for the microblock 

group. The output ACE can receive packets from the previous microblock 

in its own group or another group, or from a conventional ACE. 

An application must include the microcode portions of these ACEs with any 

microcode of its own to create the microcode image that it downloads to each 

of the microengines as part of its initialization and startup procedure. 

l 

l 

To initialize an application, you run a startup script that loads, configures, 

and starts an input and output ACE for each port on which the application 

will receive and transmit packets. 

You combine the microblocks for the interface ACEs with any microblocks 

of your own to create the microcode image that you download to each of the 

microengines as part of the initialization and startup procedure. 

The core component of an interface ACE is written in C/C++. When your application 

creates an interface ACE during system initialization, the ACE’s initialization 

function instantiates the ingress or egress class and required helper 

classes. Depending on the IXP1200-based board configuration, the initialization 

procedure instantiates helper classes as needed for the proper types of network 

interface ports. 

Interface ACE 

Crosscalls 

At runtime, an application can configure both physical and logical aspects of an 

input port using the crosscall interfaces exported by the input ACE. The input 

ACE exports two interfaces: 

l 

l 

The portMgmt interface defines operations that allow an application to 

control the physical configuration of a port. The physical properties of a port 

include such things as its port number, MAC address, and whether it is 

enabled. 

The logicalIfMgmt interface defines operations that allow an application 

to control the logical configuration of a port. An application can define 

multiple logical interface configurations for each port and treat each logical 

interface as a virtual port. This allows the application to associate multiple 

IP addresses with one physical port. 

Only the input ACE defines IXA IDL crosscall interfaces; it is not necessary to 

configure output ACEs after installation. To invoke these crosscalls, a program 

or ACE must connect to the server and initialize the client side of each interface 

before making any calls. The initialization routine of the input ACE initializes 

the server side of its crosscall interfaces. 

80 Interface ACEs 


Initializing Interface ACEs 

A complete reference for the input ACE configuration crosscalls is provided in the 

IXA SDK Reference. 

Source Code 

Location 

The source code for the interface ACEs, including the IXA IDL and generated stub 

files for the input ACE crosscalls, can be found in the following location: 

SDKinstallpath/src/microace/aces/interface_ace 


When you initialize the IXP1200 system, using a management program or startup 

script, you specify which ports to use and provide the microcode images for each 

microengine. To use the interface ACEs, you must build their microblocks into at least 

one input and one output microcode image. 

After configuring the microengines, the management program or startup script starts 

and binds the interface ACEs, along with any other microACEs and conventional 

ACEs in the application. 

Creating a 

Microcode 

Image with an 

Interface ACE 

Microblock 

Each microengine is configured for a microcode type, that determines whether it will 

perform input or output operations, and on which type of port. When you build a 

microcode image that includes the microblock for an input or output ACE, that 

microblock determines the type of the image. The type of a microcode image is determined 

as shown in the following table: 

Type 

Slow ingress 

Slow egress 

Fast ingress 

Fast egress 

Other 

Description 









The image does not contain an interface ACE microblock. 

When you specify the microcode images, either programmatically using the RmUeng- 

SetUcode function or in the system configuration file, using the file keyword, you 

specify the type. The Resource Manager than assigns each microcode image to a 

microengine with the correct type. 

Interface ACEs 81 



When you allow the Resource Manager to configure the microengines (by using the 

startup script or the Resource Manager function RmSetPortConfig), it sets the types 

automatically. You can see how the types are assigned using the Resource Manager 

function RmUengGetConfig. To specifically configure a microengine with a type, use 

the Resource Manager function RmUengSetConfig. 

Starting, 

Naming, and 

Binding 


You can create, start, and bind interface ACEs programmatically, using Resource 

Manager functions in a management program, or you can use the startup scripts and 

system configuration file for the IXDP1200 Advanced Development Platform. See 

Chapter 4, “Configuring and Starting IXA Systems.” 

You can specify any ACE name for an interface ACE, but they are, by convention and 

by default, named ifaceInput and ifaceOutput. The interface ACEs reside at the 

root level of the Name Server’s name space. To refer to them and their targets, use 

names in the form: 

/ifaceInput/target_name 

Because it is a microACE, the input ACE’s default target must be statically bound 

to the microACE containing the next microblock in the processing pipeline. You can 

create a static binding in either of the following ways: 

l 

l 

Programmatically, use the Resource Manager function RmBindMicroAce, rather 

than the Resolver function ix_res_bind. For example: 

RmBindMicroAce ("/ifaceInput/default", "/MyAce"); 

In the configuration file for the startup script, use the static flag for the bind 

statement. For example: 

bind static ifaceInput/default MyAce 

For example, suppose the application contains a microACE named MyAce, and the 

microcode puts the microblock for MyACE next in the processing pipeline after the 

input ACE. Use the following code to create the static bindings: 

RmBindMicroAce ("/MyAce/default"); "/ifaceOutput"); 

RmBindMicroAce ("/ifaceInput/default", "/MyAce"); 

An output ACE can receive packets from a previous microblock in the same group, 

from another microblock group, or from another ACE. Any ACE that needs to 

transmit packets must create a target for transmission and bind it to the output ACE. 

For example, suppose the core component of MyAce receives packets from another 

ACE, and defines a target, Tx, with which to transmit them. Use the following code 

to create a dynamic binding between the Tx target of MyAce and the output ACE: 

ix_res_bind ("/MyAce/Tx", "/ifaceOutput"); 

To create this dynamic binding in the configuration file, use the bind statement as 

follows: 

bind dynamic MyAce/Tx ifaceOutput 



The Input ACE 


The input ACE can be configured to receive packets from either the 10/100BaseT 

Ethernet or the gigabit Ethernet ports. The input ACE is implemented as a microACE. 

The core component is written in C++. 

The microblock handles packet flow by getting packets from the port, and passing 

them to the next microblock in its group. It never sends packets up to its core component. 

The input ACE does not define any targets other than the default target, which 

you must bind statically to the microACE containing the next microblock in the 

group. You do not normally bind the targets of other ACEs to the input ACE. 

The input ACE core component manages the physical and logical configurations for 

each port, and keeps statistics on traffic flow. It acts as a server for the exported 

configuration crosscalls. 

Configuring 


Using 

Crosscalls 

Only the input ACE defines an IXA IDL crosscall interface, as it is not necessary to 

configure the output ACE after installation. Applications can invoke the input ACE 

crosscalls to do the following: 

l 

l 

l 

l 

Set physical port properties such as MAC address 

Set logical interface properties such as a list of IP addresses 

Enable or disable a network interface port 

Retrieve various interface statistics such as the number of bytes sent or received 

The crosscalls operations are defined in two interfaces, the portMgmt interface and 

the logicalIfMgmt interface. The input ACE acts as a server for crosscalls and 

executes crosscalls on a per-port basis. The initialization routine of the input ACE 

initializes the server side of both interfaces. 

To invoke these crosscalls, a program or ACE must initialize the client side of the 

interfaces before making any calls to the crosscall reference stub functions. A 

complete reference for the exported crosscalls is provided in the IXA SDK Reference. 

When you generate the input ACE configuration crosscall C files from the provided 

interface definition file, ingress_ace.idl, the IXA IDL compiler produces the 

following files that you must link into the call client: 

Generated File 

ingress_ace_stub.c 

ingress_ace_stub.h 

ingress_ace_cb.c 

ingress_ace_cb.h 

Description 

Contains the stub functions for crosscall references 

and the client-side interface initialization and termination 

functions. 

Contains the templates for deferred operation callback 

functions, and the callback function vector table. Use 

the templates to implement handler functions for 

returned values, and modify the vector table to point to 

the function implementations. 




Responding to 

Input ACE 

Configuration 

Crosscalls 

Input ACE configuration crosscalls that retrieve values are defined as deferred operations. 

To handle the values that are returned asynchronously from these calls, the 

client program or ACE must define handler callback functions. 

For each deferred operation, the IXA IDL compiler generates a function template for 

the callback function in the ingress_ace_cb.c file. The crosscall client must implement 

a callback function based on the template. It must then modify the callback 

function vector table in the ingress_ace_cb.c file to point to the implementation 

rather than the template function. 

The following code fragment shows an example of how to change the callback function 

vectors. 

ix_base_t baseArray[0]; /* for IDL interface */ 

ix_error err; 

ix_ace *pAce = (ix_ace *)pIng; /* our global variable */ 

CC_VMT_portMgmt* pVmtPort = 0; 

err = sk_portMgmt_init (&baseArray[0],&pAce->cap[0]); 

if (err) 

IGA_ERROR_CHAIN(err, sk_portMgmt_init); 

err = getCCVMT_portMgmt(&baseArray[0], &pVmtPort); 

if (err) 

IGA_ERROR_CHAIN(err, getCCVMT_portMgmt); 

/* Fill in pointers to implementation of functions */ 

pVmtPort->_pCC_portMgmt_portGetPorts = portGetPorts; 

pVmtPort->_pCC_portMgmt_portGetConfig = portGetConfig; 

pVmtPort->_pCC_portMgmt_portSetConfig = portSetConfig; 

pVmtPort->_pCC_portMgmt_portEnable = portEnable; 

pVmtPort->_pCC_portMgmt_portDisable = portDisable; 

pVmtPort->_pCC_portMgmt_portGetFlags = portGetFlags; 

pVmtPort->_pCC_portMgmt_portSetFlags = portSetFlags; 

pVmtPort->_pCC_portMgmt_portAddMacAddrFilter = 

portAddMacAddrFilter; 

pVmtPort->_pCC_portMgmt_portRemoveMacAddrFilter = 

portRemoveMacAddrFilter; 

pVmtPort->_pCC_portMgmt_portGetMacAddr = portGetMacAddr; 

pVmtPort->_pCC_portMgmt_portSetMacAddr = portSetMacAddr; 

pVmtPort->_pCC_portMgmt_portSetPromiscMode = portSetPromiscMode; 

pVmtPort->_pCC_portMgmt_portClearPromiscMode = 

portClearPromiscMode; 

pVmtPort->_pCC_portMgmt_portClearStats = portClearStats; 

pVmtPort->_pCC_portMgmt_portGetSnmpStats = portGetSnmpStats; 

DBG_MSG("ingressAceIdlInit : portMgmt init successful.\n"); 

Managing 

Physical Ports 

The operations defined in the portMgmt interface manage the physical port configuration 

of an IXP 1200 system. An application can use these crosscalls to do the 

following: 



The Output ACE 

l 

l 

l 

l 

l 

l 

Initialize and configure the 10/100BaseT ports under the 21440 Octal MAC, and 

gigabit ports under the IXF1004. 

Enable and disable ports for reception (Rx). 

Add and remove MAC addresses for address filtering on a port. 

Turn promiscuous mode on or off for a port. 

Gather SNMP/RMON statistics for a port, and clear statistics. 

Store configuration information, including port type (slow or fast), MTU, MAC 

address, and port status flags, for retrieval by applications. 

Managing 

Logical Port 

Configuration 

The operations defined in the logicalIfMgmt interface manage the logical, or 

virtual, port configuration of an IXP 1200 system You can define multiple logical 

interfaces for a port. An application can use these crosscalls to do the following: 

l 

Create, maintain, and destroy logical interface properties for a port. Properties 

include: 

— IPv4 address 

— Mask 

— Interface number 

— Interface name 

— Status flags. 

l 

Store the logical interface information for retrieval by applications. 


The output ACE can be configured to transmit packets on either the 10/100BaseT or 

the gigabit Ethernet ports in an IXP1200 system. 

The output ACE is a microACE, whose core component is implemented in C++. It 

manages the physical properties of a network interface port, and its own microblock. 

It does not manage the logical interface properties. The output ACE does not require 

run-time configuration, and does not export any crosscalls. 

Other ACEs can bind targets to an output ACE and send packets to it. The output 

ACE relays these packets to the microcode block for transmission. 

To manage the physical port properties, the output ACE defines an internal method 

API to do the following: 

l 

l 

Initialize and configure the 10/100BaseT ports under the 21440 Octal Mac, and 

fast ports under the IXF1004. 

Enable ports for transmission. 

The output ACE is always paired with a corresponding microcode block for an input 

ACE that receives packets on the same port, although the input microcode block need 

not be in the same group. 




Sample Output 

Configurations 

There are many possible combinations of modes, starting ports, and starting FIFOs 

for the output microblocks. This section outlines some of the possible configurations 

that would work best on an IXP1200 Evaluation Platform, and provides some sample 

setup code for them. 

The following table lists some suggested configurations of one or more output 

microblocks for particular setups. 

Supported 

Ports 

Output 

Microblock 

Mode Start Port Start FIFO 

8 100Mb SlowEgress 16 TFIFO entry 0 0 

8 100 Mb 1 

1Gb 

SlowEgress 8 TFIFO entry 0 0 

FastEgress 8 TFIFO entry 8 1 

2 1Gb FastEgress 8 TFIFO entry 8 0 

FastEgress 8 TFIFO entry 9 1 

16 100 Mb SlowEgress 8 TFIFO entry 0 0 

SlowEgress 8 TFIFO entry 8 1 



Chapter 8 

Stack and Library ACEs 

This chapter describes system-defined ACEs provided with the SDK for specific 

purposes, such as communicating with the operating system’s TCP/IP stack and 

performing layer-three unicast packet forwarding. The chapter contains the 

following sections: 


l “The Stack ACE” on page 88 

l “The L3 Forwarder Library ACE” on page 89 

l “The L2 Bridging Library ACE” on page 91 

l “The NAT Library ACEs” on page 94 

Overview 

The IXA SDK provides the stack ACE to represent the Linux * TCP/IP stack, and 

library ACEs to perform typical networking tasks such as packet forwarding. 

The stack ACE is a conventional ACE. To send packets to the stack you bind ACE 

targets to the stack ACE, and to receive packets from the stack you bind its target to 

an application or output ACE. 

Library ACEs are generally (but not always) implemented as microACEs. To integrate 

library microACEs into your application, you link and compile the microblocks 

with the microblocks of interface and application-specific microACEs. For more 

information on microACE architecture, see Chapter 6, “Writing MicroACEs,” and 

Chapter 6, “MicroACE Support Services,” in the IXA SDK Reference. 

You load and bind stack and library ACEs as part of system initialization. The distribution 

includes scripts for loading and starting the supplied ACEs. You modify the 

startup script’s configuration file to load and start the proper system and library 

ACEs for your application. 


Stack and Library ACEs 87

The Stack ACE 

Sample applications that use the library ACEs in various configurations can be found 

in the following location: 


The Stack ACE 

The stack ACE is a system-defined ACE that integrates Linux TCP/IP stack with an 

IXA application. 

The stack ACE is implemented as a conventional ACE combined with a kernel-mode 

Ethernet device driver. The stack ACE appears to the Linux kernel as an Ethernet 

device, and to the IXA system as an ACE. 

The stack ACE does not perform any classification. When it receives a packets 

received from any ACE bound to it, the stack ACE directs that packet to the Linux 

TCP/IP stack. 

The stack ACE contains one target, named tx. Any packet received from the TCP/IP 

stack is directed to the ACE bound to that target. The following example shows the 

stack ACE bound directly to a network interface in both directions: 

TCP/IP stack 

stack ACE 

tx Target 

default target bound to stack ACE 

tx target bound to output ACE 

input port 

input ACE 

output ACE 

output port 

Starting and 

Configuring 

the Stack ACE 

The stack ACE is, by convention, named stackAce, but you can give it any name. The 

stack ACE target is named /stack_ACE_name/tx. The source code and ACE executable 

file can be found in the following location: 

SDKinstallpath/src/microace/aces/kstack 

You can start and bind the stack ACE using OMS calls in a manager program. For 

example, use the following code to bind the target of the stack ACE to the output 

interface ACE, and the application-defined ARP target of MyAce to the stack ACE: 

ix_res_bind ("/stackAce/tx", "/ifaceOutput"); 

ix_res_bind ("/MyAce/ARP", "/stackAce"); 

88 Stack and Library ACEs 


The L3 Forwarder Library ACE 

You can also start and bind the stack ACE using the startup and configuration scripts. 

In the ixsys.config file: 

l 

l 

l 

Use the ace keyword to start the stack ACE. 

Create dynamic bindings for it using the bind keyword. 

Use the sh keyword to run the stackconfig configuration utility. 

This utility uses the port configuration specified in the ixsys.config file. You do not 

need to specify further configuration details. For example, the following statement 

launches the stackconfig configuration utility, specifying the name of the stack 

ACE as stackAce, and giving the location and name of the system configuration file: 

sh ./stackconfig stackAce ./ixsys.config 

For examples of using the startup utilities and configuration files, see Chapter 4, 



The IXA SDK includes a library ACE that performs layer-three forwarding, which 

you can include in routing applications. The library ACE is implemented as a 

microACE. 

The L3 forwarder microACE is an IP version 4 unicast forwarder. It takes in IP 

packets from one network interface port, decides what their destinations are, and 

sends them out through another port based on the decision. It makes the routing decision 

and forwards the IP packet according to the standard described by the Internet 

Engineering Task Force (IETF) RFC 1812. The L3 forwarder ACE conforms to this 

standard in the following area: 

l 

l 

l 

l 

Verifying that an IP packet is valid (checksums, bad source and destination 

addresses, options, and so on), 

Updating the various fields (Time to Live (TTL), options), 

Performing the destination lookup 

Dealing with errors (typically through the Internet Control Message Protocol 

ICMP). 

For more information on this standard, see www.ietf.org. 

The L3 forwarder microACE forwards IP packets based on a given routing table, and 

performs address resolution using the Ethernet Address Resolution Protocol (ARP). 

Like all microACEs, the forwarder contains a microblock and a core component: 

l 

l 

The microblock performs fast-path forwarding of IP version 4 packets. For exception 

packets, such as those requiring options processing, the microblock sends the 

packet to the core component. 

The core component is implemented in C++. In addition to processing exception 

packets, the core component generates ICMP error messages, handles all ARP 

messages and maintains the routing tables. 


Stack and Library ACEs 89


Starting the 

Forwarder 


The forwarder library ACE is named by convention L3Fwdr, but you can give it any 

name when you launch it. To use the forwarder ACE, you typically configure the 

L3Fwdr microblock as the next block in each microblock group that contains an input 

ACE microblock, so that it accepts packets from the input ACE. If your application 

needs to do other processing on incoming packets first, you might need other ACEs 

between the input ACE and the forwarder. 

To start and initialize the L3 forwarder, use thel3config configuration utility. This 

utility uses the port configuration specified in the ixsys.config file, then adds 

routing table and ARP entries for the L3 forwarder library ACE according to specifications 

in the L3 forwarder configuration file. Launch this utility from 

theixsys.config file as a shell command. 

For example, the following statement launches the l3config configuration utility, 

specifying the name of the L3 forwarding library ACE as L3Fwdr, and giving the locations 

and names of both configuration files: 

sh ./l3config L2Bridge ./ixsys.config ./l3forwarder.config 

Binding the 

Targets 

The forwarder ACE defines two targets, /forwarder_name/out_if and 

/forwarder_name/stack. The forwarder directs packes as follows: 

l 

l 

It sends locally destined packets to stack target. These include broadcast, multicast, 

and unicast packets whose destination is one of the IP addresses assigned to 

the system. 

It sends all other valid, correctly routed packets to the out_if target. 

If no further processing is needed for outbound destinations, you can statically bind 

the out_if target directly to the output interface ACE, and configure the microcode 

processing pipeline in the same way. To do further processing on outbound packets, 

bind the out_if target to the next ACE in the processing pipeline. Dynamically bind 

the out_if target to the output ACE or other handler ACE so that the forwarder’s 

core component can also use it to transmit packets. 

Similarly, you can dynamically bind the stack target directly to the stack ACE so that 

the forwarder’s core component can pass packets with local destinations to the Linux 

TCP/IP stack. If your application needs to do further processing on locally destined 

packets, bind the stack target to another handler ACE. 

For an example of starting, configuring, and binding the forwarder ACE, see 

Chapter 3, “Compiling and Testing Applications.” 

Configuring 

the Forwarder 

The L3 forwarder configuration file uses keyword statements to set up the initial 

configuration of the routing table and ARP cache for the L3 forwarder library ACE. 

l 

The configuration keywords are described in detail in the IXA SDK Reference. 

l For an example of using the startup utility and configuration file, see Chapter 4, 




The L2 Bridging Library ACE 

The L3 forwarding ACE exports a crosscall interface that your application uses to 

manipulate the routing table, ARP table, and otherwise configure the behavior at run 

time. The crosscall operations are organized into functional areas as follows: 

l 

l 

l 

l 

l 

l 

Route table calls allow you to: 

— Add and delete route table entries 

— Perform route table lookups 

— Print the route table to a file for debugging 

Forwarding configuration calls allow you to get and set configuration flags to 

control forwarding behavior 

ARP table and configuration calls allow you to: 

— Add and delete ARP table entries 

— Perform ARP table lookups 

— Get and set the ARP sleep time, default age, and backoff values 

ICMP calls allow you to get and set the ICMP drain value, sleep time, and queue 

depth 

A statistics call allows you to get statistical information about forwarding activity 

for a particular network interface port. 

Interface calls allow you to: 

— Get and set the layer 2 MAC address of a port 

— Get and set layer 3 IP addresses of a port 

— Enable and disable ports 

— Get and set the MTU for a port 

The crosscalls are described in detail in the IXA SDK Reference. For more information 

on using crosscalls, see Chapter 11, “Communication Within an Application.” 


The L2 bridging library ACE implements a layer-two bridge according to the 

ISO/IEC 15802-3 standard, as described in the ANSI/IEEE Std 802.1D, 1998 Edition. 

It is implemented as a microACE. Like all microACEs, the forwarder ACE contains a 

microblock and a core component: 

l 

l 

The microblock performs fast-path forwarding of unicast IP version 4 packets 

between networks or network segments. It maintains an 8000-entry forwarding 

table, and a logical port state that determines how and whether it transmits 

packets on a port. It sends exception packets to the core component. 

The core component processes exception packets. It defines targets that the 

microACE uses to forward packets to the output interface ACE or to other ACEs, 

such as the stack ACE or L3 forwarding ACE. 

The core component administers the port states and the MAC forwarding table. 

It performs aging for dynamic (learned) table entries, and deletes them after the 

maximum aging time. It exports crosscalls that allow an application to configure 

the table and port states at run time. See “Configuring the L2 Bridger” on page 94. 

Stack and Library ACEs 91 



Packet 

Processing 

The microblock drops any packet whose source address is of type multicast or broadcast, 

whose size exceeds port MTU or is less than 64 bytes (runts), or that has a 

reserved destination address. 

Packet handling depends on the logical port state: 

l When a port is disabled, any packet destined for the port is dropped. 

l When a port is blocked or listening and the incoming packet is a BPDU packet, it 

is sent to the core component. Otherwise it is dropped. 

l 

l 

When a port is learning, the microblock adds the source MAC address of an 

incoming packet to the forwarding table. 

When a port is forwarding, the microblock learns the MAC address and performs 

all packet forwarding. In this state, if the destination MAC address on received 

packet is equal to the MAC address of the port, this packet is meant for local 

administration, L3 forwarding, or a nonroutable protocol. The microblock queues 

the packet to a local target for handling. 

The core component performs a flooding operation for an incoming packet if the 

destination address is not found in the forwarding table. Flooding copies packets, 

and can be resource intensive. You can limit flooding to a subset of ports by assigning 

ethertype protocols to specific ports. 

The following exception conditions cause the microblock to send a packet to the core 

component: 

Condition 

BPDU 

Learn 

Learn and Forward 

Description 

The incoming port is in the blocked, listening, learning, or forwarding 

state and the destination address matches the BPDU multicast 

address. 

This occurs under either of the following conditions: 

l The receiving port is in learning state and the source MAC address 

was not found in the MAC forwarding table. 

l The receiving port is in forwarding state but the output port was not 

in the forwarding state, and the source MAC address was not found 

in the MAC forwarding table. 

The microblock adds an entry to the MAC forwarding table, providing 

the source MAC address, the ingress port number, and the dynamic 

entry type. An event handler in the core component ages the learned 

entries. 

The source MAC address is not found in the MAC forwarding table, 

the destination MAC address is found, and both the input and output 

ports are in forwarding state. 

The microblock adds the entry and the core component ages it, as for 

the Learn condition. 




Condition 

Learn and 

Flood 

Description 

Neither the source nor the destination addresses are found in the 

MAC forwarding table, and the input port is in forwarding state. 

This packet is flooded to ports that are configured for the protocol type 

found in the ethertype of this packet. 

Learn and ARP The destination MAC address is addressed to this port but the source 

MAC address is not found in the MAC forwarding table. The input port 

is in forwarding or learning state. 

The core component learns the address and passes the packet to 

either the L3 forwarder ACE or the stack ACE. 

Flood 

Destination MAC address is not found in the forwarding table but the 

source MAC address has found a match. 

When the input port is in forwarding state, the packet is flooded to 

ports that are configured for the protocol type found in the ethertype 

of this packet. 

When the input port is in learning or forwarding state, the microcode 

adds a MAC forwarding entry for a unicast, multicast, or broadcast 

packet. 

Starting the L2 

Bridger 

The L2 bridging library ACE is named by convention L2Bridge, but you can give it 

any name when you launch it. The source code, including the ACE executable file 

and microblock source, can be found in the following location: 

SDKinstallpath/src/microace/aces/l2bridge_ace 

To use the bridging ACE, you typically configure the L2Bridge microblock as the 

next block in each microblock group that contains an input ACE microblock, so that 

it accepts packets from the input ACE. If your application needs to do other 

processing on incoming packets first, you might need other ACEs between the input 

ACE and the bridger. 

The bridger ACE defines two targets, /bridger_name/out_if and 

/bridger_name/stack. 

To start and initialize the L2 bridger, use the l2config configuration utility. This 

utility uses the port configuration specified in the system configuration file, then 

adds route table entries and sets logical port properties specific to the L2 bridging 

library ACE according to specifications in the L2 bridge configuration file. Launch 

this utility from the ixsys.config file as a shell command. 

For example, the following statement launches the l2config configuration utility, 

specifying the name of the L2 bridging library ACE as L2Bridge, and giving the locations 

and names of both configuration files: 

sh ./l2config L2Bridge ./ixsys.config ./l2bridge.config 



The NAT Library ACEs 

Configuring 

the L2 Bridger 

The L2 bridge configuration file uses keyword statements to initialize the routes and 

port configuration needed by the L2 bridging ACE. All the commands operate at the 

layer-two level. The logical port configuration does not effect the physical behavior 

of the port. 

l 

The keywords are described in detail in the IXA SDK Reference. 

l For an example of using the startup utility and configuration file, see Chapter 4, 


The ACE exports a crosscall interface that your application uses to manipulate the 

routing table and port configuration at run time. 

You can use the crosscalls to: 

l 

l 

l 

l 

l 

l 

l 

Enable and disable the collection of port activity statistics, in the form of RFC1493 

MIB attributes and tables, and retrieve the statistics. 

Update the MAC forwarding table, associating a destination port with destination 

MAC addresses and entry types (static or dynamic). 

Update the time that learned MAC forwarding table entries are allowed to age 

before being automatically removed. 

Update port states. A port state can be disabled, blocked, listening, learning, or 

forwarding. 

Enable and disable Ethernet bridging for a port. 

Enable and disable IP bridging for a port when routing is disabled for that port. 

Configure port groups for any ethertype protocol, to enable bridging for 

nonroutable protocols. 

The crosscalls are described in detail in the IXA SDK Reference. For more information 

on using crosscalls, see Chapter 11, “Communication Within an Application.” 


The NAT library application consists of two ACEs, the NAT microACE and the NAT 

controller, a conventional ACE. Together, these ACEs perform network address 

translation according to rules that you provide. 

Packet 

Processing 

The specific rules for network address translation are defined by your application in 

the NAT controller’s access control lists (ACLs). There are two types of ACL: 

l 

l 

A filter ACL contains filter rules that specify what actions to take on packets with 

specific destination addresses. The possible actions are pass, drop, and NAT. 

The NAT ACLs contains network address translation rules. When a packet 

matches a filter rule that specifies the NAT action, the ACE searches for a 

matching NAT rule in the NAT ACLs. The NAT controller maintains ACLs for the 

following types of network address translation: 

— Static 

— Dynamic 




— IP masquerade (port translation) 

— Virtual server (load balancing) 

The NAT microACE maintains a cache of translations, which it receives from the 

NAT controller. The microblock receives incoming packets, parses the header, and 

looks for a translation in its cache. If it finds one, it performs the specified IP address 

translation and forward the packet to the next microblock in its group. 

If the microblock finds no translation in the local cache, it flags an exception and 

sends the packet to the core component. The core component sends all packets it 

receives (from its own microblock or from other ACEs) to the NAT controller. 

The NAT controller searches its filter rules to determine whether network address 

translation should be performed for the packet. If it should, the ACE searches the 

appropriate NAT rules to find the correct translation. 

When it has found a suitable translation, the NAT controller passes both the translation 

and the packet back to the microACE. The microACE core component updates 

the translation cache, then passes the packet back to the microblock for processing. 

Special 

Handling 

By default, the NAT ACEs also handles the following special-case packet types: 

l FTP packets 

l TCP fragments 

l ICMP error packets 

You can choose to disable any of these provided handlers and replace them with your 

own handlers. To do this: 

1. Use the enableApps crosscall to disable the handler for a packet type. (For more 

information, see the IXA SDK Reference.) 

2. Provide your own handler ACE for the packet type. 

3. Bind the ALG target of the NAT microACE to your handler ACE. 

The following sections briefly describe how the NAT ACEs handle each special case. 

FTP Packet Handling 

An FTP PORT or PASV reply command embeds the IP address and port numbers in 

the payload. To perform address translation for a PORT or PASV reply command, the 

FTP handler parses the payload to find the embedded IP address and port number. 

l 

l 

If the embedded IP address is the same as the IP address in the IP header that 

requires translation, then the handler translates the embedded address also. 

For IP masquerading (port translation), the handler translates the embedded port 

number, assigning a port from the ACE’s pool. 




When the handler modifies the embedded IP address or port, it also changes the 

number of bytes in the payload and saves the number in the other_data field of the 

FLOW_DATA structure in SDRAM. This causes a change in the sequence number or 

acknowledgement number for subsequent packets. The handler recalculates the IP 

checksum to reflect the data changes. 

TCP Fragment Handling 

When the NAT microACE receives fragments, it assumes that all of the header fields 

are in the first fragment. Upon receiving the first fragment, the fragment handler 

performs the NAT table lookup. 

l 

l 

If no entry is found, the microACE flags an exception and sends the packet buffer 

to the control ACE. 

If an entry is found, it begins collecting the fragments in a buffer. If all fragments 

are not received within the specified timeout period, the buffer is cleared. When 

the datagram is complete, the microACE begins address translation on the fragments. 

If it is a TCP or UDP packet the fragment handler performs address translation for 

both the TCP/UDP header and the IP header in the first fragment. For the 

remaining fragments, it translates only the IP header addresses. The handler 

recalculates all checksums to reflect the data changes. 

ICMP Error Packet Handling 

When the NAT microACE receives an ICMP packet, the ICMP handler checks that it 

is an ERROR packet, which contains an embedded IP header for the packet that 

caused the error. The ICMP handler performs address translation for the IP header 

embedded in the message, and recalculates the checksums accordingly. It modifies 

the following: 

l 

l 

l 

The IP addresses and checksum of the IP header embedded in the data of the 

ICMP packet. 

The ICMP header checksum. 

The normal IP header checksum. 

If the ICMP packet is not an ERROR message, the handler sends it to the default 

target. The handler does not store any state for ICMP packets. 

Starting the 

NAT ACEs 

To use the NAT library ACEs, you must start both the NAT microACE and the NAT 

controller ACE. 

l 

The NAT microACE is named by convention nat, but you can give it any name 

when you launch it. To start the microACE, you can use the microace keyword in 

the system configuration file. For example: 

microace nat ./Nat none 0 5 natc 3 

l 

The NAT controller is named by convention natc, but you can give it any name 

when you launch it. To start the NAT controller, you can use the ace keyword in 

the system configuration file. For example: 




ace natc ./natctlr none 2 nat 1 

The source code, including the ACE executable files and microblock sources, can be 

found in the following locations: 

SDKinstallpath/src/microace/aces/nat_ace 

SDKinstallpath/src/microace/aces/nat_ctlr 

You can configure the microblock to get packets directly from the input interface ACE 

microblock, or from the microblock of another processing ACE such as the L3 

forwarder. It can transmit packets directly to an output ACE, or to another microACE 

for further processing. 

To initialize the NAT controller, use the natconfig configuration utility. This utility 

sets up the initial ACLs and rules according to specifications in the NAT configuration 

file that you supply. Launch this utility from the ixsys.config file as a shell 

command. 

For example, the following statement launches the natconfig configuration utility, 

specifying the name of the NAT controller ACE as natc, and specifying the configuration 

file as nat.config in the same directory: 

sh ./natconfig natc ./nat.config 

Binding the 

Targets 

The NAT microACE defines the following targets: 

Target 

Description 

PASS 

CONFIG 

DROP 

Bind this target statically to the microACE containing the next microblock 

in the group, as defined by the dispatch loop. 

When the microACE finds a cached translation for an incoming 

packet, it performs address translation as required then sends the 

packet to this target to continue normal processing. 

Bind this target to the NAT controller ACE. 

When the microACE finds no cached translation for an incoming 

packet, it sends the packet to this target so that the NAT controller 

can provide a new translation. 

This target must remain unbound. 

The microACE drops packets by sending them to this target. The 

packet buffer is automatically freed when passed to an unbound target. 




Target 

ALG 

DEFAULT 

Description 

Bind as required for your application. 

When one of the special packet-handling features (for FTP, TCP fragments, 

or ICMP errors) is disabled, the microACE sends packets of 

that type to this target. 

You can define rules to send packets to this target for applicationdefined 

handling. (ALG stands for application-level gateway.) 

Bind as required for your application. 

The microACE passes all non-TCP/UDP packets (except ARP packets) 

to this target. 

Configuring 

the NAT library 


The NAT controller ACE maintains a data structure containing access control lists 

(ACLs) which in turn contain the application-defined rules. 

l 

l 

The ACLs are created and initialized by the natconfig startup utility according 

to the information you provide in the NAT configuration file. 

The NAT controller exports a crosscall interface. Use these crosscalls to add and 

delete ACLs and rules at run time. 

When adding a rule, you can specify the rule’s position in its ACL. When searching 

the rules, the NAT controller applies the first matching rule to an incoming packet. 

l 

l 

l 

For more information on startup and configuration, see Chapter 4, “Configuring 

and Starting IXA Systems.” 

For more information on using crosscalls, see Chapter 11, “Communication 


For detailed information on the configuration file keywords and configuration 

crosscalls, see the IXA SDK Reference. 



Chapter 9 

Classifying Packets Using NCL 

This chapter describes how an ACE classifies incoming packets using its classification 

code, which you write in Network Classification Language (NCL). 


l “How ACEs Handle Packets” on page 99 

l “What’s in the NCL Rules File” on page 100 

l “Defining Protocols” on page 102 

l “Defining Rules” on page 101 

l “How Rules Are Evaluated” on page 103 

l “What Rules Do” on page 104 

How ACEs Handle Packets 

An ACE does three things with a packet: 

l Classifies it 

l Acts on it 

l Disposes of it 

Packets are received by the IXP1200 as network traffic flows through it. A packet 

arrives at an ACE from the source to which it is bound as a destination target, as 

described in Chapter 5, “Controlling Packet Flow.” The source of a packet could be, 

for example, either a network interface or another ACE earlier in the processing 

chain. The ACE classifies each incoming packet according to classification rules 

defined in the ACE’s NCL rules file. 


Classifying Packets Using NCL 99

What’s in the NCL Rules File 

As a result of the classification, NCL rules trigger action functions that are defined in 

the ACE’s action code. Action functions can act on packets by examining or retrieving 

their contents, or dispose of packets by sending them to targets. An action function 

can make a final disposition, ending the classification process for that packet, or it can 

tell the ACE to continue with the classification process and evaluate more rules. 

What’s in the NCL Rules File 

An ACE classifies incoming packets according to the protocol and predicate definitions 

in its NCL rules file. Based on the classification, rules trigger action functions 

defined in the ACE’s action code. The rules file and action file are compiled into a 

single object, which you associate with the ACE in the ACE initialization function 

you define. 

The NCL rules file has two general parts. In the first part, you define the protocols 

and predicates that are the basis of classification. In the second part, you define the 

rules, which trigger specific actions based on how a packet satisfies the predicates. In 

addition to these basic elements, you can define sets and searches in the NCL rules 

file. 

Classification 

Elements 

The basic classification elements you define in the NCL rules file are rules and protocols. 

l 

l 

A rule determines whether some statement is true for the current packet. If it is, 

the rule specifies an action to take. The action is a function that you defined in the 

action code that is part of the same ACE as the NCL rules file. 

A protocol definition describes a set of fields of particular lengths. A protocol is 

usually added on as a header to one or more other nested protocols. The definition 

states which other protocols can be nested, and where they start. 

For convenience, you can also define named predicates to use in the rules and 

protocol definitions. A predicate determines whether something is true of a current 

packet — for example, whether it conforms to a certain protocol, or whether a particular 

field has a particular value. Predicates are named Boolean expressions, which 

can contain other predicates and Boolean expressions. You can define predicates as 

part of a protocol definition or separately. 

Sets and 

Searches 

NCL and the Action Services Library (ASL) together support data tables called sets. 

Sets associate application-defined data with packets. You define named searches associated 

with a specific set, which determine whether the current packet has a matching 

element in the set, based on the values of specified fields. 

You define and name the sets and searches in the NCL rules file, then use the 

compiler to generate corresponding objects in the action code. The sets are implemented 

on initialization. You populate the sets with data through actions. 

Searchable sets define collections of packets which are associated with each other by 

virtue of their contents. A set member (element) matches packets with a specific 

combination of field values. If you want to form collections on structural criteria, such 

100 Classifying Packets Using NCL 


Defining Rules 

as “the set of all packets with IP header lengths greater than twenty bytes,” use a classification 

predicate rather than a searchable set; see “Defining Protocols” on 

page 102. 

Sets are an efficient way to track a large number of classes of packets. They allow you 

to keep state information for all packets that have the same values in specific fields. 

For example, you can count the number of packets that flow between any two specific 

IP address pairs, or maintain state for each TCP stream. 

For more information on sets and searches, see Chapter 13, “Using Sets of Data to 

Classify Packets.” 

Defining Rules 

NCL rules determine what action to take, based on the classification. A rule consists 

of two parts: 

l 

l 

A predicate part 

The predicate part of a rule is a Boolean expression that describes the conditions 

a packet must meet to have the specified action performed on it. 

Predicates might include static comparisons of packet contents or comparisons 

against dynamically-created state. 

An action part 

The action part of a rule is the name of an action function to be executed when the 

predicate is true, along with any additional arguments the named function 

expects. The action function performs some action upon the incoming packet. 

The following example shows the parts of a rule: 

rule allpackets { ether } { action_all() } 

Name of this rule 

NCL keyword 

Predicate 

Action 

The predicate part of the rule can be the name of a predicate defined earlier in the file 

or in an included file, or it can be a Boolean expression that can, in turn, use named 

predicates. A predicate uses packet protocol elements that are defined earlier in the 

NCL rules file or in an included file. You access protocol fields using the form 

protocol_name.field_name; for example, ip.src. In a predicate, the name of the 

protocol currently being parsed evaluates to TRUE. 

The action part of the rule contains the name of an action function defined in the 

compiled action code that is part of the same ACE. You can pass arguments to the 

function, as required by its definition. The action is executed only when and if the 

predicate part of the rule evaluates to TRUE. 

Classifying Packets Using NCL 101 


Defining Protocols 

Defining Protocols 

A rule determines whether its predicate is true by looking at fields in the current 

packet. The fields are interpreted according to the protocol definitions in the NCL 

rules file. 

A protocol definition names and describes a protocol. It names and describes the 

header fields that make up the protocol, and describes the relationship among 

multiple protocols. You generally define protocols in the first main section of an NCL 

rules file, immediately after the file inclusions and constant definitions, and before 

the rules. 

The IXA SDK distribution contains an NCL include file that defines the TCP/IP 

protocol. You can include this file in your application, and also use it as a template for 

defining other protocols. The sample file is located in the following directory: 

SDKinstallpath/include/ix/ncl/ix_tcp.ncl 

Protocols often contain other protocols. The keyword demux in a protocol definition 

identifies other protocols that can be nested within it. (The keyword comes from 

demultiplexing, the process of extracting nested protocols from the protocols that 

contain them.) When a packet arrives, the IXP1200 parses the protocol definitions to 

classify the packet. When it reaches the demux statement, the parser evaluates the 

expressions in the order in which they appear. The first expression that evaluates to 

TRUE identifies the nested protocol, and the parser continues into the indicated 

protocol definition. 

For example, the IP protocol definition contains the following demux statement that 

specifies what other protocols could be nested in an IP packet, and at what offset they 

would be found: 

demux { 

invalid { ip_bad at 0 } 

badsrc { ip_badsrc at 0 } 

(proto == 1) { icmp at hlen } 

(proto == 2) { igmp at hlen } 

(proto == 6) { tcp at hlen } 

(proto == 17) { udp at hlen } 

default { ip_unknown_transport at hlen } 

} 

While a protocol is being parsed, the protocol’s name becomes a Boolean expression 

that evaluates to TRUE. For example, if the IP protocol is currently being parsed, the 

expression ip evaluates to TRUE. 

The following example shows an excerpt from the NBtcpip.ncl include file. This 

excerpt defines the header fields for Ethernet packets, defines a reusable Boolean 

function (predicate) for the protocol, and specifies the demultiplexing (demux) 

method to high-layer protocols. 



How Rules Are Evaluated 

protocol ether { 

NCL protocol definition 

dst { ether[0:6] } 

NCL field definition 

src { ether[6:6] } 

typelen { ether[12:2] } 

snap { ether[14:6] } 

NCL predicate description 

type { ether[20:2] } 

predicate isnap { (typelen

What Rules Do 

For more information on what actions can be taken and how to define them, see 

Chapter 10, “Initializing and Acting on Packets in an ACE.” 

What Rules Do 

A rule can simply check the protocol type and take an appropriate action. For 

example, a VPN application might have a rule to check for an IPSec packet. When the 

rule succeeds, the action decrypts the packet. The rule might look like this: 

rule check_ipsec { ipsec } { action_decrypt () } 

A rule can pass field values to the action. For example, the following rule passes the 

source and destination addresses: 

rule check_ip { ip } { action_ip (ip.src, ip.dst) } 

The rule itself can check the source or destination address, or both, against a particular 

address, or table of addresses. 

A rule that checks a specific address might look like this: 

rule check_src { ip.src == 10.10.10.30 } { action_A() } 

You can use sets to keep tables of addresses, and named searches to check incoming 

packet addresses against the table. For more information on sets and searches, see 

Chapter 13, “Using Sets of Data to Classify Packets.” 

The rule can check other fields in the packet. For example, in an intrusion detection 

application, a rule might check whether a TCP packet is part of an HTTP stream. The 

rule might look like this: 

rule check_http { tcp && (tcp.sport == 80 || tcp.dport == 80) } 

{ action_scan () } 

When successful, this rule passes the packet to an action function, where it is queued, 

reordered, and then searched for interesting strings. If the function finds such a 

string, it sends a notification to the control module using a crosscall. 

For more information on: 

l Defining action functions, see Chapter 10, “Initializing and Acting on Packets in 

an ACE.” 

l 

Crosscalls, see Chapter 11, “Communication Within an Application.” 



Chapter 10 

Initializing and Acting on Packets in an ACE 

This chapter describes the initialization and action phases of an ACE. It explains what 

is in the ACE’s C code files, how to write them, and what kind of things an ACE 

might do. 


l “ACE Code Overview” on page 105 

l “Initializing the ACE” on page 106 

l “Defining Action and Utility Functions” on page 108 

l “What Action Functions Do” on page 110 

ACE Code Overview 

Each ACE executable contains a C initialization file, linked with a C action file that is 

associated with an NCL rules file. 

l 

l 

The initialization file creates and initializes the ACE object, and also creates and 

initializes any other subclasses, objects, and structures that the ACE will need. 

The entry point is the application-defined ix_init function, which acts as a main 

function for the ACE. A corresponding ix_fini function cleans up upon exit by 

destroying all objects created during initialization. 

The action file contains the action and callback function definitions. These are 

entry points that implement the behavior of your application in response to 

incoming packets, crosscalls, or application-defined events. The action part also 

contains any other utility functions that your application might call from the entry 

point functions. 


Initializing and Acting on Packets in an ACE 105

Initializing the ACE 

You write ACE initialization and action code using the following: 

l 

l 

The C/C++ runtime environment 

The action services library (ASL), which provides: 

— Support for the ACE structure and model, including a basic structure for 

representing network data packets (the ix_buffer), and for sending them to 

different destinations on the network (the ix_target) 

— Support for associating application-defined data with packets using data sets 

— Support for scheduling application-defined events 

The ASL API is described in detail in the IXA SDK Reference. 


In the initialization portion of your action code file, you define any subclasses or 

other data structures that the application will need. The initialization function, 

ix_init, must create and initialize the ACE itself, as well as any other objects and 

data the ACE will need. 

Defining ASL 

Objects 

Each ACE executable file is associated with one ACE, which is represented by an 

ix_ace structure. Your initialization function must allocate such an object and 

initialize it by calling ix_ace_init. 

Normally, an application defines a customized ACE structure that contains an 

ix_ace and other associated objects and data. Your ACE initialization function must, 

in addition to creating the ACE itself, create and initialize all structures associated 

with the ACE. These can include: 

l 

l 

l 

l 

Target objects. Each ACE automatically includes a target named default, which 

you normally bind to the egress network interface ACE or to the next ACE in the 

processing pipeline. You can also define additional targets to bind to other destinations. 

For more information, see Chapter 5, “Controlling Packet Flow.” 

Communication objects. These include crosscall and crosscall reference objects, 

from subclasses produced by the IDL compiler and customized with your application’s 

crosscall methods. For deferred crosscalls, you must also define and set 

the crosscall callback function. For more information, see Chapter 11, “Communication 


Data set and set element objects. For each data set, the ACE initialization must 

declare and create a set structure (ix_set) with the same name and size that was 

declared for the set in NCL. It might also populate the set on initialization. For 

more information, see Chapter 13, “Using Sets of Data to Classify Packets.” 

Event objects. These allow you to schedule application-defined events for the 

ACE. In addition to creating and initializing the event structure (ix_event), you 

must define and set an event callback function to perform the desired operation. 

106 Initializing and Acting on Packets in an ACE 



Your ACE also typically contains methods or functions to perform applicationspecific 

operations, such as invoking crosscalls or initiating searches, as well as callback 

functions for crosscalls and events. For more information, see “Defining Callbacks” 

on page 109 and “Defining Utility Functions” on page 109. 

Defining the 

Initialization 

Function 

Your ACE initialization file must contain a definition for the “main” function for the 

ACE, ix_init(). In this function, you must create and return the ix_ace object for 

the ACE to which the code belongs. In addition to creating the ACE object, the function 

must perform any other initialization the ACE needs. It must create targets and 

other associated objects and structures, populate sets, or initialize other data structures. 

The following is an example of an application-defined ACE initialization function 

that creates an ACE containing one target in addition to the default, named 

MyTarget: 

ix_error ix_init (int argc, char **argv, ix_ace **acep) 

{ 

//allocate ace, pass to ace init 

ix_ace myace; 

ix_target mytarget; 

} 

ix_ace_init (myace, argv[1]); //name of ACE is passed in 

ix_target_init (mytarget, myace, "MyTarget"); 

// error case 

// (error handling code here) 

//success, return 

acep = myace; 

return 0; 

The Resolver calls the ACE’s ix_init function when the application creates an ACE. 

A manager program can create the ACE by calling ix_res_create_ace(), passing 

the name of the ACE as its first argument. (See Chapter 2, “OMS Global Services 

API,” in the IXA SDK Reference.) You can also create the ACE directly from the 

command line or a script, using the utility ixace. (See Chapter 8, “Command-Line 

Tools,” in the IXA SDK Reference.) 

The ACE initialization process automatically creates a CAP through which the ACE 

can communicate with the OMS, and starts the ACE loop, which listens for packet 

arrival and crosscall events. 

The ACE loop continues to run until the manager module deletes the ACE by calling 

ix_res_delete_ace, which in turn calls the ACE’s ix_fini function. The ACE’s 

action code must contain a definition for the function ix_fini which correctly 

deletes all objects and structures created during initialization. 

Initializing and Acting on Packets in an ACE 107 


Defining Action and Utility Functions 


The action code file must define the methods and functions that implement the 

behavior of your application. You can implement behavior in any of the following 

ways: 

l 

l 

l 

Action functions 

An action function is executed when an NCL rule’s predicate is TRUE for an 

incoming packet. Action functions can call methods or other functions directly, or 

schedule events that result in the execution of callbacks. 

Callbacks 

Callbacks are executed in response to crosscall completions or scheduled events. 

You define a callback as a function of the appropriate type. 

Other utility functions 

You must provide definitions for utility functions. These are not entry points. To 

execute a utility function, you must call it from an action function or callback. 

Defining 

Action 

Functions 

Actions are function entry points implemented according to the calling conventions 

of the C/ C++ programming language. An action function is executed when an NCL 

rule predicate is satisfied for an incoming packet. The rule must pass any arguments 

that you have defined for the action function, and the action function must return one 

of the disposition codes that tell the ACE whether to continue passing the packet to 

other action functions triggered by successful classification rules. 

NOTE: 

Due to limitations in the gcc compiler, it is recommended that you avoid the 

use of type bool arguments in action functions. Use unsigned int instead. 

Action Function Return Values 

An action function that you define must return one of the following constant values: 

Constant Value Description 

RULE_CONT 0 Return RULE_CONT if the action has only observed the 

buffer, and additional rules and actions within the context of 

the current ACE remain to be processed. 

Return this value from functions that do not take ownership 

of the network packet buffer. 

RULE_DONE 1 Return RULE_DONE to terminate processing of rules and 

actions within the context of the current ACE, for example, 

when a buffer has been sent to a target or stored for later 

processing. 

Return this value from functions that take ownership of the 

network packet buffer. 




CAUTION: If your action function does not return one of these codes, your application 

can be corrupted when the action function returns, and the corruption may 

not be detectable. 

Predefined Default Action Function 

One action function, ix_action_default, is already defined in the ASL. This function 

routes a packet to the ACE’s default target. It returns the code RULE_DONE, which 

halts all further processing for the packet. It take no arguments. To call this function 

in an NCL rule, use a rule like the following: 

rule passip { ip } { ix_action_default() } 

This would pass all IP packets through to the ACE’s default target without further 

processing. 

For More Information 

For more information on defining action functions, see the IXA SDK Reference. 

Defining 

Callbacks 

In the action part of your action code file, you define the callbacks that are executed 

in response to various events. You can define the following kinds of callbacks: 

l 

l 

Deferred crosscall callbacks 

The callback or service function for a crosscall implements the behavior to be 

executed when a deferred crosscall is completed. 

The IXA IDL compiler generates a skeleton for each crosscall callback function, 

which takes as its arguments the output parameters defined for the corresponding 

call in the crosscall interface. You must modify the skeleton to define the 

behavior of the function. 

For more information on call handler callbacks, see Chapter 11, “Communication 


Scheduled event callbacks 

The ix_event mechanism provides for execution of functions at arbitrary times 

in the future. An action function can schedule, reschedule, or cancel an event, or 

change the function that it executes. The event callback function implements the 

behavior to be executed at the scheduled time. 

For more information on event callbacks, see Chapter 4, “The ASL Core Support 

Package API,” in the IXA SDK Reference. 

Defining Utility 

Functions 

You can define utility functions in the action file, be called from entry points such as 

action functions and callbacks. For example, an ACE that serves as a crosscall client 

typically contains a utility function to build a message and invoke a remote call, using 

the crosscall reference or stub. This utility function can be called, for example, by an 

action function in response to the receipt of a packet containing specific information. 



What Action Functions Do 


You can define action functions to respond to the successful application of a rule in 

any way you want. Actions can do any of the following: 

l 

l 

l 

l 

Pass the current packet to any target 

Modify a packet before passing it to a target 

Increment and decrement application-specific counters 

Schedule an event for execution at a later time 

l Build and send messages using crosscalls. For more information, see Chapter 11, 

“Communication Within an Application.” 

l 

l 

Maintain data sets, creating elements to insert in a set, and deleting elements after 

removing them from a set. For more information, see Chapter 13, “Using Sets of 


Call other functions or methods 

The following table shows some typical actions you might define for different types 

of applications. Notice that, while the action is triggered by a rule that checks a particular 

condition, the action itself can continue to check conditions before deciding what 

to do. 

Table 1: 

Application Type Classification Action 

Firewall 

Controls access by maintaining 

a set of acceptable source 

addresses 

If packet IP source 

address is in my table of 

addresses that have 

access to my network 

Route the packet to the 

appropriate location inside 

my network 

Firewall 

Translates packet addresses 

based on a set of address 

mappings 

If packet IP destination 

address matches a 

known address for 

inbound traffic 

If the packet IP source 

address matches a 

known address for outbound 

traffic 

Change the destination 

address to the new address 

specified by the matching 

set element 

Recompute checksums 

Change the source address 

back to the original mapping 

address specified in 

the matching set element 

Recompute checksums 




Table 1: (Continued) 

Application Type Classification Action 

Load-balancing 

Redirects packets to leastloaded 

servers by maintaining 

a set of possible destination 

servers 

If the IP source and destination 

match an element 

in the server set 

If the IP source and destination 

do not match any 

element in the server set, 

pass the pointer to where 

the record should go to 

the action 

Perform address translation 

(NAT) to change destination 

to value from matching 

element 

Recompute the checksum 

Send the packet to the identified 

server 

Use a load-balancing algorithm 

to determine the 

server to which the connection 

should go 

Create a new element for 

the server and add it to the 

set 

Perform NAT on the packet 

and send it to the identified 

server 

Intrusion detection 

Network monitoring 

If the packet is part of a 

TCP stream 

If the packet is HTTP and 

has a specified IP source 

address 

Search the packet for interesting 

strings 

If found, notify the application 

using an upcall 

Search the packet for the 

name of the web page of 

interest 

If found increment a 

counter called mywebpage 

Quality of service 

Maintains higher and lower 

priority queues for transmitting 

traffic 

If the IP destination 

address equals that of an 

internal server 

If the IP source address 

equals that of a preferred 

customer 

Place the packet on a high 

priority queue for transmission 

Place the packet on a high 


If the IP destination 

address is an external 

web site and the source 

address is from a low-priority 

department 

Place the packet on a low 


VPN 

If the packet is an IPSec 

packet 

Decrypt the packet using 

cryptographic API calls. 






Chapter 11 

Communication Within an Application 

This chapter introduces the crosscall mechanism that is used for communication 

between software objects through the Object Management System (OMS). It contains 

the following topics: 


l “Defining Crosscall Interfaces” on page 116 

l “Defining Call Operations” on page 118 

l “Invocation Types for Operations” on page 120 

l “Initializing and Terminating Interfaces” on page 125 

l “Invoking Crosscall Functions” on page 130 

l “Passing Crosscall Arguments” on page 133 

Overview 

ACEs often need to communicate with one another or with a managing program for 

various reasons. For example: 

l 

l 

l 

l 

ACEs can send alerts or status reports to a managing program. 

Data processor ACEs can receive control messages and data from control ACEs. 

Data processor ACEs can send occasional packet data to control ACEs for special 

processing 

ACEs can exchange messages among themselves to coordinate packet processing. 

Because ACEs and their managing programs might be running on different platforms 

and be written in different languages, the IXA provides a communication mechanism 

based on remote procedure calls. The remote calls that you define for an IXA application 

are known as crosscalls. 


Communication Within an Application 113

Overview 

The OMS acts as a message broker for crosscalls. It provides marshalling and format 

conversion to handle differences in byte order and word size between different 

processors. 

Defining 

Interfaces 

You do not need to implement the entire crosscall infrastructure in your application. 

Instead, you define an interface, using an interface definition language, IXA IDL, that 

is provided with the IXA SDK. In the interface definition file you create a prototype 

for each operation, which determines whether a call is synchronous or asynchronous 

as well as defining the return type and argument types and directions for each call. 

In addition to the call prototypes, the interface definition file includes definitions for 

data structures used by the crosscalls. 

You compile an IXA IDL interface definition using the supplied compiler, tao_idl. 

The compiler generates several C source and header files that implement the calling 

infrastructure. You include the generated code with your application code. The only 

additional code you need to write is the implementation of the application-specific 

crosscall behavior. The compiler supplies template functions with the proper calling 

protocol, based on the interface you defined. 

Making and 

Receiving 

Remote Calls 

An ACE or an external object can both make and receive remote function calls. An 

object that receives calls acts as a crosscall server. An object that makes calls acts as a 

crosscall client. 

l 

l 

The call server receives the call from the client and executes the call function. 

Depending on how you define the crosscall interface, it can send a response to the 

client or not. The server contains the crosscall function implementation, as well as 

the generated code for the calling infrastructure. 

The call client makes a remote call to the call server. It contains a generated crosscall 

reference stub function, as well as generated code for the calling infrastructure. 

Depending on the type of call, it can also contain a callback function for handling 

an asynchronous response from the server. 

An ACE or task can act as a server for more than one crosscall, and can act as a client 

for any number of crosscalls as well. 

Crosscall 

Client 

Crosscall 

Server 

Crosscall 

Client 

Crosscall 

Client 

Crosscall 

Client 

Crosscall 

Server 

Crosscall 

Server 

114 Communication Within an Application 


Overview 

Each call client or server must open a communication session with OMS. The session 

requires a dedicated communications channel called a communication access process 

(CAP). The call client or server can be either an ACE or a non-ACE program. 

l 

l 

When you create an ACE, the initialization procedure automatically creates a 

CAP for that ACE, and the ACE runtime polls that CAP for crosscall events in its 

main loop. When you initialize crosscalls, extract the ACE’s CAP using 

ix_ace_to_cap. 

A non-ACE program that acts as a crosscall client or server must initialize itself 

with the OMS as a task, using the ASL function ix_task_init. You can add the 

task to the OMS name space using the function ix_ns_add_task. 

Run the crosscall session in a separate thread. When you initialize crosscalls, 

extract the task’s CAP using ix_task_to_cap. The thread must poll the CAP for 

crosscall events using ix_cap_loop. 

Application code 

CAP, crosscall reference 

Remote procedure call 

Client task 

OMS 

Optional response 

Packet 

flow 

CAP, crosscall 

Packet Related 

classification actions 

Server ACE 

When to Use 

Crosscalls 

Applications typically use crosscalls for configuration. For example, predefined 

library ACEs and system ACEs export crosscall interfaces that allow your application 

to configure them by making remote calls. 

Crosscalls are not an efficient way to forward packets. You can use a crosscall to send 

an occasional packet to another ACE for special processing or examination, or to send 

data retrieved from a packet. However, applications should use targets rather than 

crosscalls to pass packets between ACEs in the course of normal processing, as the 

target mechanism is optimized for packet traffic and is much more efficient. 

Communication Within an Application 115 


Defining Crosscall Interfaces 


You define a crosscall interface for an ACE or other object in a .idl file, using the IXA 

Interface Definition Language (IXA IDL). The syntax and grammar of the IXA IDL, 

which is similar to C/C++, is completely described in Chapter 7, “IXA Interface Definition 

Language (IXA IDL),” in the IXA SDK Reference. 

An IXA IDL compiler is provided with the IXA SDK. This compiler converts IXA IDL 

files into customized C files for making remote function invocations. In creating these 

C files, the compiler transparently handles hardware dependent issues such as types, 

byte order, and alignment. You never need to write C code for the OMS interaction. 

Generated 

Files 

The compiler generates file names by appending a suffix to the IXA IDL source file 

name for skeleton, crosscall, stub, and callback files. From the source file 

idlname.idl, the IXA IDL compiler produces the following C files: 

Server/Client Generated Files Description 

Server only idlname_sk_c.h Crosscall skeleton header. 

idlname_sk_c.c 

idlname_cc_c.h 

idlname_cc_c.c 

Crosscall skeleton source. 

Crosscall template header, includes skeleton 

header. 

Crosscall template source, includes skeleton 

source. 

Use the crosscall template as base for 

implementation. 

Server and client idlname_stub_c.h Crosscall reference header. 

idlname_stub_c.c Crosscall reference source. 

idlname_cb_c.h 

idlname_cb_c.c 

Callback template header. 

Callback template source. 

Use the callback template as a base for 

implementation if there are any deferred 

calls. 

l 

l 

Skeletons: These files contain all the code needed for the interaction between the 

crosscall (server), the crosscall reference (client), and the OMS. 

Use these files without modification. Include the header in the server’s source 

code, and link the source file into the server’s executable. 

Crosscalls: For each operation, the crosscall template file contains a function 

template, and a crosscall virtual method table (VMT) that points to the function 

implementations. 

Include the header file in the crosscall server’s source code, and link the source 

file into the server’s executable. Initialize crosscalls in the server using the generated 

initialization functions provided in this file. 




Use the function templates as a model to provide the call function implementations. 

To avoid losing your changes on recompilation, keep the implementations 

in a separate source file. Replace the VMT pointers to the template functions with 

pointers to your implementations. 

l 

l 

Stubs: These files implement the crosscall reference stub functions, and also 

contain infrastructure needed by the server. Use these files without modification. 

Include the header in both the client’s and the server’s source code, and link the 

source files into the client’s and server’s executables. Initialize crosscalls in the 

client using the generated initialization functions provided in this file. 

Callbacks: For any deferred call operations, the compiler creates template callback 

functions in these files. (See “Invocation Types for Operations” on page 120.) If 

there are no deferred operations, these files are empty. When there are callback 

functions, the files contain a callback virtual method table (VMT) that points to 

the function implementations. 

If there are callback functions, include the header in both the client’s and the 

server’s source code, and link the source files into the client’s and server’s executables. 

Use the templates as a model to provide the callback function implementations. 

To avoid losing your changes on recompilation, keep the implementations in a 

separate source file. Replace the VMT pointers to the template functions with 

pointers to your function implementations. 

Organizing 

Call 

Operations 

IXA IDL files are structured as a set of modules, which, in turn, are composed of one 

or more interfaces and data structure definitions. 

l 

l 

Each module defines a name space or scope for a set of interfaces. You can use 

modules to group interfaces, so that you can repeat common operation names 

(such as ReportError, for example). Interface names must be unique only within 

a module. 

Each interface contains the signatures of individual operations. Operation names 

must be unique only within an interface. Each operation maps to one crosscall 

server function and its stub client function. Each deferred operation also maps to 

a callback function for handling the asynchronous response. 

An IXA IDL file can contain more than one interface. ACEs and other objects can 

import or export more than one interface. Each interface can contain one or more 

operations. 

You can divide individual call operations among interfaces, or define them all in a 

single interface, depending on how you want to organize your application’s functionality. 

For example, here is a sample IDL file that defines three crosscall interface definitions, 

each containing two operation call signatures, in one module: 

module myXcalls 

{ 

interface XcallOne 

{ 

//.... 



Defining Call Operations 

XcallOneFn1 (args); 


//.... 

}; 

interface XcallTwo 

{ 

//.... 

XcallTwoFn1 (args); 


//.... 

}; 

interface XcallThree 

{ 

//.... 

XcallThreeFn1 (args); 


//.... 

}; 

}; 

Alternatively, you could define and create a single crosscall that exports all six operations: 

module myXcalls 

{ 

interface XcallOneTwoThree 

{ 

//.... 







//.... 

}; 

The two approaches are equally valid. In either case the compiler generates eight 

files. Using separate interface definitions to group operations functionally can make 

your code more readable. 


In each operation signature in an interface definition you declare the return type, the 

directions and types of all arguments, and the invocation form. Together, these determine 

whether and how values can be returned from the remote function invocation. 




Operation 

Names 

You name each operation in an interface definition, but the operation name is unique 

only within the interface. Similarly, the interface name is unique only within a 

module. To translate this scoping and create unambiguous names, the IXA IDL 

compiler produces function names by prepending the module and interface names 

to the operation name. 

For example, the following interface definition repeats the operation names in two 

interfaces: 

module mod1 

{ 

interface if1 

{ 

op1 (args); 

op2 (args); 

}; 

interface if2 

{ 

op1 (args); 

op2 (args); 

}; 

}; 

In the crosscall source file that results from compilation, the function skeletons are 

named as follows: 

mod1_if1_op1 

mod1_if1_op2 

mod1_if2_op1 

mod1_if2_op1 

If the interface definition includes nested modules or interfaces, they are included in 

the generated name from the outside in. For example, in the following interface definition, 

module mod2 is nested inside module mod1: 

module mod1 

{ 

interface if1 

{ 

op1 (args); 

op2 (args); 

}; 

{module mod2 

interface if2 

{ 

op1 (args); 

op2 (args); 

}; 

}; 

}; 

In this case, the generated names for the two op1 operations in the two modules are 

as follows: 



Invocation Types for Operations 

mod1_if1_op1 

mod1_mod2_if2_op1 


There are three forms of remote function invocation, which determine whether the 

caller receives a response, and if so whether it is synchronous or asynchronous: 

l 

l 

l 

One-way calls receive no response. 

Two-way calls elicit a synchronous response. The OMS blocks the caller until it 

receives the response. (This form can only be used by external crosscall clients. 

ACEs cannot block.) 

Deferred calls allow an asynchronous response. The call returns immediately with 

a simple result indicating whether the call was successfully sent. When the call 

completes the OMS invokes a callback handler specified by the caller. 

You declare the type of an operation with a keyword before the operation signature 

in the interface definition. The type of the operation affects how input and output 

arguments are mapped to the generated functions. For more information, see 

“Passing Crosscall Arguments” on page 133. 

One-way 

Operations 

When a client calls a one-way function, the object calling the function does not block. 

It makes the call and then immediately continues processing, while the remote object 

executes the remote function. 

l 

l 

Declare a one-way operation using the keyword oneway before the return type 

declaration in the operation signature. 

A one-way function invocation cannot return a value. Therefore, you must 

declare the return value as void and all parameters as in. 

Since the calling object has no way of knowing whether the function executed 

successfully, use the one-way operation where such knowledge is not essential or 

where the success of the function call is tested by invoking another function. 

The following example shows the signature for a one-way operation in an interface 

definition: 

oneway void doSomething(in char* name); 

The generated skeleton and stub functions for this call are defined to take the input 

argument, and return an error token (ix_error) . 

Two-way 

Operations 

When a client calls a two-way function, the calling object blocks (waits for the function 

to execute and return) before continuing its own processing. This allows the 

remote object to respond, and the caller to determine the success of the execution. 

l 

Declare a two-way operation using the keyword twoway before the return type 

declaration in the operation signature. This is the default invocation type, so if 

you do not declare the type, the operation is two-way. 




l 

l 

A two-way operation can have output arguments. You can use these to return 

values from the remote object. 

A two-way operation can return a value. The compiler maps the return value to 

an output argument before generating the C code. 

NOTE: 

This form can only be used by external crosscall clients. ACEs cannot block. 

They can serve two-way calls, but cannot be clients for them. 

Here is an example of the prototype for a two-way operation in an interface definition: 

twoway void doSomething(in int value, out char* name); 

This operation has an out parameter that will return a value to the caller. 

All generated functions return an ix_error error token. The generated stub function 

(that the client uses to invoke the call remotely) is defined to take both the input and 

the output argument. For output arguments in a two-way function, the call client 

must allocate a variable of the proper type and pass its address to the call stub function. 

Upon return, the stub function places the output data in the output variable. 

Deferred 

Operations 

In a deferred operation, the calling object expects the remote function to execute and 

return but does not block processing until a response is received. It calls the stub function 

and then immediately continues processing, while the remote object executes the 

remote function. The calling object stores a callback function in a common data area 

and executes the callback when a reply is received from the remote function that was 

called. In this case, the caller can determine the success of the execution of the function 

on the remote object by the remote object response. 

l 

l 

l 

Declare a deferred operation using the keyword deferred before the return type 

declaration in the operation signature. 

A deferred operation can have output arguments which are passed to the callback 

function. 

A deferred operation can return a value. The compiler maps the return value to 

an output argument before generating the C code. 

Here is an example of the prototype for a deferred operation in an interface definition: 

deferred void doSomething (in int value, out char* name); 

The operation returns void but has an out parameter that will return a value to the 

callback function in the client. 

Handling Asynchronous Responses with a Callback Function 

When an interface contains a deferred operation, the compiler generates a template 

definition for a callback function in the callback header and source files. You must use 

the template to implement the callback function definition. 




The generated stub function takes the input (in and inout) arguments. The OMS 

passes the output (inout and out) values to the callback function. All generated functions 

return an error token (ix_error). When the client allocates resources for a stub 

function variable, it is responsible for freeing those resources when the application no 

longer needs the value. 

The callback function template takes the following arguments: 

l The interface token, of type ix_base_t. 

l The error returned by the call function, of type ix_error. 

l All output (out and inout) arguments defined for the deferred call operation 

with which it is associated. 

For example, for the deferred operation defined above, the compiler generates a callback 

template with the following signature: 

ix_error mod1_if1_doSomething_cb (ix_base_t* basep, ix_error 

anError, char* name); 

Specifying 

Timeouts 

For two way and deferred operations, you can specify a timeout. For example: 

twoway long op1(in long val) context("TIMEOUT=5"); 

The integer value determines the number of seconds the client will wait for a 

response before returning an error. If you do not specify a timeout, the default 

timeout value is determined by the OMS variable IX_OMS_SYSTEMTIMEOUT. 

You cannot specify a timeout of 0 seconds. 

Declaring 

Argument 

Directions 

Depending on the invocation type (see “Invocation Types for Operations” on 

page 120), a call can sometimes return values through output arguments. You declare 

operation arguments as input, output, or both input and output using the keywords 

in, out, and inout. The direction keyword precedes the type declaration for each 

argument. 

For example, the following operation signature declares a single input argument: 

oneway void accept_source(in appair_t appair); 

The following operation signature declares two arguments, where the first is input 

and the second is output: 

deferred void read_accept_list (in long listlen, 

out aplist_t aplist); 

The call function that the compiler generates for an operation must always return an 

ix_error. If you declare a return type for an operation in the interface definition, the 

compiler automatically transforms it to an output variable. For example, the declaration 

long op(); is transformed to: 

void op (out long _return_long) 



Integrating Crosscalls with Applications 

The generated call template for an operation takes as parameters all declared arguments 

in the interface definition. In general, if a parameter can be used for output 

(out or inout), the caller must pass an address and you must define the call function 

to dereference it. For more information, see “Passing Crosscall Arguments” on 

page 133. 

The generated call reference stub takes all input arguments (in and inout), which it 

passes to the call function in the server. For a synchronous two-way operation, it also 

takes the addresses of output arguments (out and inout), which it uses to store 

response values. 

For an asynchronous deferred operation, the output (out and inout) arguments 

become parameters in the template callback function. 


To define a crosscall, use the following steps: 

1. Create a crosscall interface definition in IXA IDL file, file.idl. 

2. Compile the file on the command line, using the tao_idl compiler: 

> tao_idl file.idl 

The IXA IDL compiler generates code for both the client and server from the interface 

definition. The compiler output includes C source and header files that 

contain skeletons of the call functions, as well as stub functions with which to 

invoke them. These files implement the crosscall infrastructure. 

3. Include both the skeleton headers and the stub headers in the call server, and link 

the executable with the skeleton and stub C sources. 

4. Include the stub header in the call client, and link the executable with the stub 

source. 

5. For each operation in an interface definition, provide a crosscall function that 

actually implements the desired service, according to your application requirements. 

The compiler generates a template crosscall function for each operation, which 

you can use as a basis for your implementation. 

— For prototyping, you can modify the generated files directly. Include the 

generated crosscall header in the call server, and link the executable with the 

modified crosscall C source. However, the generated file is overwritten each 

time you compile the IXA IDL, and your changes are lost. 

— For a real application, write the crosscall definition in another source file, 

making sure it conforms to the template. During initialization, you must 

change the crosscall VMT structure to point to your crosscall implementation 

instead of to the template function. 

6. If the interface specifies any deferred (asynchronous) operations, provide a callback 

function implementation for each one. This is a function that is executed 

when the call completes. 




The compiler produces a template callback function for each deferred operation. 

As for the crosscall template, you can modify the generated template to provide a 

callback definition, or provide an implementation based on the template in 

another file. You must change the callback VMT structure to point to your callback 

implementation instead of to the template function. 

7. Initialize each crosscall interface as part of the initialization process in both client 

and server. Initialization must be complete before the client makes any calls. See 

Appendix , “Communication Within an Application” on page 125. 

Threads and 

Crosscalls 

To make two-way calls, a client must use multithreading. If the call client is an ACE, 

which must be single-threaded, or if the client program needs to be single-threaded 

for any other reason, you must use deferred calls rather than two-way calls to return 

information to the caller. For a deferred call, you must define a callback function to 

handle the returned results, basing it on the template created by the IXA IDL 

compiler. 

An external program that communicates through the OMS is known as a task. To 

create the task, use the ASL function ix_task_init, and extract the CAP using 

ix_task_to_cap. Add the task to the Name Server using ix_ns_add_task. When 

the crosscall client opens a connection to the call server, it passes the task name. (See 

“Invoking Crosscall Functions” on page 130.) 

In communicating with the Name Server and Resolver, a task can use either an asynchronous 

session and entry points (ix_ns_open, ix_res_open) or a synchronous 

session and entry points (ix_ns_open_sync, ix_res_open_sync). Synchronous 

communication is easier to write and to read, although it requires a separate thread 

for the session. ACEs must use asynchronous sessions to communicate with the 

OMS, because they cannot block. For more information synchronous and asynchronous 

OMS sessions, see the IXA SDK Reference. 

The thread you create for synchronous communication in a task must poll for crosscall 

events using ix_cap_loop or ix_cap_poll. 

Crosscalls and 

Library ACEs 

Predefined library and system ACEs supplied by Intel ® typically act as crosscall 

servers. They export their crosscall interface definitions, as well as the generated stub 

files resulting from the compilation. You can regenerate the stub files from the original 

interfaces if necessary. 

Any ACE or task in your application can act as a crosscall client to a library or system 

ACE by including the generated stub code, initializing the crosscall interfaces, and 

calling the stub functions. 

You must not modify the generated stub code that is provided. If an interface 

includes deferred operations, you must define callback handlers based on the 

provided templates. These handlers are part of your application and are not 

supported by Intel. 



Initializing and Terminating Interfaces 


The client and server programs must each provide code to initialize and terminate its 

interaction with the OMS crosscall mechanism. Initialization makes the client and 

server programs ready to communicate through the OMS. The client can make stub 

calls successfully only after initialization is complete. 

For each interface defined in the IXA IDL file, the compiler generates client initialization 

and termination functions in the stub file, and server initialization and termination 

functions in the crosscall file. 

Initializing the 

Client 

The client initialization function has a generated name in the form 

stub_module_interface_init. It has the following prototype: 

ix_error stub_module_interface_init 

(ix_base_t *ifbasep, 

ix_cap *clientcap); 

Argument 

ifbasep 

clientcap 

Description 

A pointer to the crosscall base structure (token) for this interface. For 

each interface that the client will use, the initialization code must create 

a token of type ix_base_t, and pass it to the interface initialization 

function. 

A pointer to the CAP for this call client, the structure used for OMS 

communication. To provide this argument, convert the ACE or task 

structure for the client to an ix_cap using the ASL functions 

ix_ace_to_cap and ix_task_to_cap. 

The interface base structure, or token, keeps all required information for the specific 

interface, until the application releases it after calling the interface’s termination function. 

The ix_base_t structure must not reside in read-only memory. Before creating 

it, the application should initialize the memory for the structure to zero. For example: 

memset(basep,0,sizeof(ix_base_t)); 

The termination function for the interface has the following signature: 

extern ix_error stub_module_interface_fini (ix_base_t* basep); 

Client 


Example 

The following example shows how to initialize and terminate a task client for the 

ixa_c_Example1 interface. 

1. Create and initialize a task, and extract the CAP structure used for OMS communication. 

Several interfaces can use the same CAP. 

ix_error err = 0; 

static ix_task* pTask = NULL; 

static ix_cap* pCap = 0; 

pTask = malloc(sizeof(ix_task)); 




if (pTask == NULL) 

{ 

err = ix_error_new(0,0,err, "%s - ix_task structure allocation 

failed!\n",localFunctionName); 

goto err_label1; 

}; 

err = ix_task_init (pTask, 

"debugClientCap"); 

if (err) 

{ 

err = ix_error_new(0,0,err, "%s - ix_task_init call 



}; 

err = ix_task_to_cap (pTask, 

&pCap); 

if (err || !pCap) 

{ 

err = ix_error_new(0,0,err, "%s - ix_task_to_cap call 



}; 

2. For two-way operations declared in the IDL interface, create and start a worker 

thread: 

/* Thread run function */ 

static ix_error idl_thread_run(void* cookie, void** dummy) 

{ 


(void)dummy; 

ix_error_init(16, 128); 

fprintf(stderr,"Communication thread started!\n"); 

err = ix_cap_loop((ix_cap*)cookie); 

if((err != 0) && !ix_error_is(err, 0, IX_ERROR_STOP)) 

ix_error_dump(stderr,err); 

} 

return err; 

{ 

ix_ossl_thread_t aThread; 

//utility fn provided w/SDK 

err = ix_ossl_create_thread (&aThread,idl_thread_run, 

(void*) pCap); 

if (err) 

{ 

return ix_error_new(0,0,err, 

"%s - ix_ossl_create_thread call failed!\n", 

localFunctionName); 

}; 

} 




3. Create and initialize a token for each interface: 

static const char localFunctionName[] = 

"initInterface"; ix_error err = 0; 

ix_base_t* pToken = 0; 

pToken = malloc(sizeof(ix_base_t)); 

if(pToken == 0) 


"%s :: Token allocation failed!\n", 


memset(pToken,0,sizeof(ix_base_t)); 

Use memset to initialize the token before passing it to the interface initialization 

function. 

Create and initialize a different ix_base_t token for each interface the client will 

use. Do not use the same token for initializing different interfaces. 

4. Initialize the interface by calling its generated initialization function. 

err = stub_ixa_c_Example1_init (pToken, pCap); 

if(err) 

{ 

free(pToken); 


"%s :: Token initialization failed!\n", 


} 

5. If the client defines callback functions for handling the responses to deferred calls, 

update the callback function vector table to point to the function implementations. 

See “Initializing Function Pointers” on page 130. 

6. Connect to the server. 


"connectClient"; 

static const char serverName[] = "aServer"; 


err = ix_oms_connect(pToken, serverName); 

if (err) 

{ 


"%s - ix_oms_connect failed!\n",localFunctionName); 

}; 

err = ix_oms_wait_connected(pToken); 

if (err) 

{ 


"%s - ix_oms_wait_connected failed!\n", 


}; 




If the server is already running, the connection completes immediately; otherwise 

the application either waits for a server to come up or times out. The call to 

ix_oms_wait_connected blocks. If your client is an ACE, or cannot block for any 

other reason, you must connect asynchronously (see the IXA SDK Reference for 

details). 

Connect to the server separately for each client interface. 

7. After all interface are initialized and the connection for each is completed, the 

client can make calls to stub functions in the interfaces. See “Invoking Crosscall 

Functions” on page 130. 

8. When the client is finished making calls to an interface, disconnect from the server 

connection for that interface. 


"disconnectClient"; 


err = ix_oms_disconnect(pToken); 

if (err) 

{ 


"%s - ix_oms_disconnect failed!\n", 


}; 

err = ix_oms_wait_disconnected(pToken); 

if (err) 

{ 


"%s - ix_oms_wait_disconnected failed!\n", 


}; 

return err; 

9. Call the termination function for that interface, then free its token. 


err = stub_ixa_c_Example1_fini(pToken); 

free(pToken); 

10. Shut down the thread and terminate the task. 

err = ix_task_fini(pTask); 

Initializing the 

Server 

The process is similar for the server. The compiler generates server initialization and 

termination functions in the skeleton file. The server initialization function has a 

generated name in the form sk_module_interface_init. It has the following prototype: 

ix_error sk_module_interface_init 

(ix_base_t *ifbasep, 

ix_cap *servercap); 




Argument 

ifbase 

servercap 

Description 

A pointer to the crosscall base structure for this interface. 

A pointer to the CAP for this call server. To obtain the CAP, use one of 

the ASL functions ix_ace_to_cap or ix_task_to_cap. 

The termination function for the interface has the following signature: 

extern ix_error sk_module_interface_fini (ix_base_t* basep); 

Server 


Example 

The following example shows how to initialize and terminate an ACE server for the 

ixa_c_Example1 interface: 

1. As part of the ACE initialization (ix_ace_init), extract the CAP structure. 

... 

ix_cap* pCap=0; //allocate a CAP variable 

... 

err = ix_ace_to_cap (pAce, &pCap); //extract the CAP 

if (err || !pCap) 

{ 

err = ix_error_new(0,0,err, "%s - ix_task_to_cap call 



}; 

2. Create and initialize a token for each interface: 


"initInterface"; ix_error err = 0; 

ix_base_t* pToken = 0; 

pToken = malloc(sizeof(ix_base_t)); 

if(pToken == 0) 


"%s :: Token allocation failed!\n", 


memset(pToken,0,sizeof(ix_base_t)); 

Use memset to initialize the token before passing it to the interface initialization 

function. Create and initialize a different ix_base_t token for each interface. Do 

not use the same token for initializing different interfaces. 

3. Initialize each interface by calling its generated initialization function, passing the 

token and the extracted CAP. 

err = sk_ixa_c_Example1_init (pToken, pCap); 

if(err) 

{ 

free(pToken); 


"%s :: Token initialization failed!\n", 



Invoking Crosscall Functions 

} 


4. Reset the crosscall function vector to point to the function implementations, 

rather than the templates. See “Initializing Function Pointers” on page 130. 

5. During shutdown, call the termination function for each interface, then free its 

token. 


err = sk_ixa_c_Example1_fini(pToken); 

free(pToken); 

Initializing 

Function 

Pointers 

The IXA IDL compiler creates a vector table (VMT) that the generated crosscall infrastructure 

uses to access the invocation functions. Initially, this table points to the 

generated crosscall function templates. The skeleton file defines an accessor function 

for the VMT, which you use to change the vector table to point to your function 

implementations, which you base on the generated templates. 

The accessor function for the crosscall VMT has the following prototype: 

extern ix_error getCCVMT_interface 

(ix_base_t 

*basep, 

CC_VMT_interface **pInterfaceCCVMT); 

The initialization code for the server must use this accessor to change each crosscall 

function pointer. For example: 

getCCVMT_MyInterface (pToken, &pCCVMT); 

pCCVMT->_pCC_Int1 _op1 = My_Int1_op1; 

Similarly, there is a VMT that the client uses to access any callback function for 

deferred operations. The stub file defines an accessor function for this VMT that the 

client must use to point to the callback function implementations. 

The accessor function for the callback VMT has the following prototype: 

extern ix_error getCBVMT_interface 

(ix_base_t 

*basep, 

CB_VMT_interface **pInterfaceCBVMT); 

The initialization code for the client must use this accessor to change each callback 

function. For example: 

getCBVMT_MyInterface (pToken, &pCBVMT); 

pCBVMT->_pCB_Int1 _cb1 = My_Int1_cb1; 


A call client invokes crosscall functions remotely, using the generated call stub. The 

stub has a generated name in the following form: 




ix_error stub_module_interface_callfn 

(ix_base_t ifbase, 

callargs...) 

Each stub function takes as its first argument the interface token (ix_base_t) that the 

client defined and initialized for the interface in which the call is defined. This structure 

allows the OMS to coordinate the calling operation. 

The remaining arguments of the stub function are the input arguments defined for 

the crosscall, and, in the case of a two-way call, the locations of variables in which to 

store the values of any output arguments. 

Opening a 

Crosscall 

Connection 

Before you can make any calls, the client must initialize each interface (as described 

in “Initializing and Terminating Interfaces” on page 125) and open an OMS connection 

to the call server. Because the connection operation takes some time, the client 

must make sure that the connection has been established before making calls. The 

OMS supplies a number of global functions to accomplish this in various ways. 

When the call client is an external program, you can open the connection with the 

function ix_oms_connect, then block and wait for the connection to complete, using 

the function ix_oms_wait_connected. 

An ACE acting as a call client cannot block, so it cannot wait for the connection to 

complete before continuing execution. However, before the client ACE can make any 

calls, it must make sure that the connection is open. There are two possible ways to 

do this: 

l 

l 

Open the connection with the asynchronous function ix_oms_connect_cb, than 

wait until the callback is executed before making any calls. 

Open the connection with the function ix_oms_connect, which provides no 

response, then use the function ix_oms_is_connected to check that the connection 

is open before making any calls. 

Remote Call 

Example 

The following example shows an external call client calling into an ACE. The example 

initializes the crosscall, then establishes a connection to the call server. Because this is 

not an ACE, it can block and wait until the connection is complete before making the 

calls. 

ix_error run_test(ix_cap *capp) 

{ 

ix_error err; 

ix_base_t if1; //create crosscall base structure 

long count = 0; 

long retval; 

// initialize crosscall interface 

memset(&if1,0,sizeof(ix_base_t)); //zero memory 

err = stub_toace_if1_init(&if1, capp); 

if(err) 

return err; 

// establish crosscall connect to server ACE 




err = ix_oms_connect(&if1, "myace"); 

if(err) 

return err; 

// wait for connection to complete before making calls 

err = ix_oms_wait_connected(&if1); 

if(err) 

return err; 

printf("CONNECTED!!!"); 

// make calls 

while(1){ 

err = stub_toace_if1_one_func (&base, count++); 

if(err) 

return err; 

printf("Oneway call sent. count = %ld\n", count); 

err = stub_toace_if1_two_func (&base, count++, &retval); 

if(err) 

return err; 

printf("Twoway call sent. count = %ld retval = %ld\n", 

count, retval); 

err = stub_toace_if1_def_func (&base, count++); 

if(err) 

return err; 

printf("Deferred call sent. count = %ld\n", 

count); 



Passing Crosscall Arguments 

} 

sleep(1); 

} 


The arguments that you declare for an operation in the interface definition can be 

used for input, output, or both, depending on the invocation type of the operation. If 

the operation is two way or deferred, you can also declare a return type, which is 

mapped to an output argument. 

The compiler maps the declared arguments to parameters in the generated call, stub, 

and callback functions and templates in such a way as to allow the calling program 

to pass in needed values and retrieve results. If results are expected, the client generally 

needs to allocate storage of the correct type and pass the address to the stub function. 

In general, when invoking a crosscall with an output (out or inout) parameter, the 

caller must pass either the address of a variable of the proper type or the value of a 

pointer to that type. The crosscall function being invoked must dereference the 

parameter to get to the type. For arrays, the caller must pass the address of the first 

element of the array. 

For out parameters of types string and wstring, the stub allocates storage for the 

output value. The client can use and retain that storage indefinitely. When the value 

is no longer needed, the client is responsible for freeing the memory. For all other 

types, the client must pass the address of a variable of the correct type. 

l 

l 

For in parameters, the caller must pass the value of the parameter for all of the 

basic types and enumeration types. For arrays, the caller must pass the address of 

the first element of the array. For all other structured types, the caller must pass 

the address of a variable of that type. 

For strings, the client must pass a char* or wchar_t*. 

For inout parameters, the client must pass the address of a variable of the correct 

type for all of the basic types, enumeration types, and structured types. For 

strings, the client must pass the address of a char*, and for wide strings, the 

address of a wchar_t*. For arrays, the client must pass the address of the first 

element of the array. 

The following table summarizes what a client passes as an argument to a stub function 

and receives as a result. 

Declared Data Type In Inout Out/Return 

short short short* short* 

long long long* long* 

long long long long long long* long long* 




Declared Data Type In Inout Out/Return 

unsigned short unsigned short unsigned short* unsigned short* 

unsigned long unsigned long unsigned long* unsigned long* 

unsigned long long unsigned long long unsigned long long* unsigned long long* 

float float float* float* 

double double double* double* 

long double long double long double* long double* 

boolean boolean boolean * boolean* 

char char char* char* 

wchar wchar* wchar* wchar* 

octet octet octet* octet* 

enum enum enum* enum* 

struct struct* struct* struct* 

union union* union* union* 

string char* char** char** 

wstring wchar* wchar** wchar** 

sequence sequence* sequence* sequence* 

array array array array 

Client Side 

Parameter 

Passing 

On the client side, follow these guidelines in passing parameters to a stub function: 

l 

l 

l 

Ensure that all parameter values are valid and properly initialized. 

Ensure that variables exist and are properly initialized before the stub call, then 

pass their addresses. The generated initialization function properly initializes all 

complex type parameters. 

When passing in parameters: 

— For all basic types, pass by value. 

— For complex types except arrays, pass as const type*. 

— For strings, pass as const char* or const wchar_t*. 

l 

When passing inout and out parameters: 

— For all basic types and all complex types except arrays, pass as type*. 




— For arrays, pass the address of the first element. 

— For inout strings, point to a valid zero-terminated arrays of characters. 

— For two-way calls, allocate string inout parameters on the heap, and set out 

parameters to 0. The generated stub code frees the memory before demarshalling 

the response values. The client application is responsible for making a 

copy if it needs the value. (For deferred calls, out parameters are not generated 

in the stub signature and you do not pass addresses for them to the stub 

functions.) 

The application is responsible for freeing any memory it has allocated after the stub 

call returns, before exiting the scope where the variables have been declared. For all 

structured data types, clean up by calling the generated termination function. 

l 

l 

l 

l 

The termination function frees all valid strings that are contained in complex 

structures (except sequences with the _release flag set to 0). To ensure that this 

is successful, allocate the strings on the heap. 

For inout and out string and wstring parameters, the client must free the 

addressed memory. For in parameters, the way you free the memory in the client 

depends on how you allocated the memory before passing the parameter to the 

stub function. 

For two-way calls, the client must make copies of any useful inout data because 

the variables disappear after the stub function returns. 

For deferred calls, do not free the inout and out parameters that the OMS will 

pass to the callbacks. Make copies of any useful data, as these go out of scope after 

the callback returns. 

What the Stub Function Does to Passed Parameters 

l 

l 

l 

The generated stub function does not modify in parameters. 

For inout parameters, the stub function overwrites the passed parameters with 

the new values. In the case of strings or complex types containing strings, the stub 

frees the memory to which the parameter points. In case of unbounded sequences, 

if the received buffer is bigger than the existing one, the stub reallocates memory. 

If the sequence has the _release flag set to 0, the stub does not free contained 

strings. 

For out parameters, the stub function writes the result data at the location 

provided by the caller, overwriting any data that is already there. 

Server Side 

Parameter 

Passing 

On the server side, the OMS properly initializes all parameters before passing them 

to the crosscall function. The application should allocate all strings for the crosscall 

on the heap. After the crosscall function returns and the response is sent back, the 

OMS performs the cleanup, freeing all strings contained in complex structures except 

for those contained in sequences where you set the _release flag to 0. 

For inout and out string and wstring parameters, the application must first free 

the memory that is passed in, then dynamically allocate memory for return values. 

The generated code attempts to free the memory as soon the crosscall function 

returns. If the application modifies an incoming string in place, there is no need to 

free and allocate memory for the return value. 




Passing 

Values in a 

One-way Call 

To make a one-way call, the client must do the following: 

1. Initialize the interface containing the one-way call, using the generated initialization 

function. 

2. Declare and initialize the in variables. 

3. Make the call to the appropriate stub function. The stub function does the 

following: 

— Marshals the operation ID. 

— Marshals all in variables. 

— Dispatches the call to OMS. 

— Returns. 

4. Clean up all the input variables. 

On the server side, a demultiplexing mechanism receives the call, demarshals the 

operation ID and invokes the proper call function as indicated by the operation ID. 

The OMS does the following: 

1. Creates and initializes variables for all in parameters. 

2. Demarshals all in parameters into the corresponding variables. 

3. Calls the application-defined crosscall function. 

4. Cleans up the in parameter variables. 

Passing 

Values in a 

Two-way Call 

To make a two-way call, the client must do the following: 

1. Initialize the interface containing the two-way call, using the generated initialization 

function. 

2. Declare and initialize the in, inout, and out variables. 


following: 


— Marshals all in and inout variables. 

— Dispatches the call to OMS and blocks, waiting for the response. 

— Releases all inout variables. 

— Demarshals inout and out parameters in the corresponding variables 

4. Upon return from the call, process returned values as needed. 

5. Clean up all variables. 




1. Creates and initializes variables for all in, inout, and out parameters. 

2. Demarshals all in, inout, and out parameters into the corresponding variables. 




3. Calls the application-defined crosscall function, which initializes the inout and 

out parameters to the return values. 

4. Marshals the inout and out variables. 

5. Cleans up all variables. 

When the client allocates resources for a stub function variable in a two-way call, it is 

responsible for freeing those resources when the application no longer needs the 

value. 

Passing 

Values in a 

Deferred Call 

To make a deferred call, the client must do the following: 

1. Initialize the interface containing the deferred call, using the generated initialization 

function. 

2. Declare and initialize the in and inout variables. 


following: 


— Marshals all in and inout variables. 

— Dispatches the call to OMS. 

4. Clean up all variables. 




1. Creates and initializes variables for all in, inout, and out parameters. 

2. Demarshals all in, inout, and out parameters into the corresponding variables. 

3. Calls the application-defined crosscall function, which initializes the inout and 

out parameters to the return values. 

4. Marshals the inout and out parameters into the corresponding variables. 

5. Invokes the application-defined callback function in the client, passing the 

parameters as arguments. 

6. Cleans up all variables it has created. 

When the callback function has performed the required processing on the returned 

values, the client must clean up any variables created for it. 






Chapter 12 

Crosscall Example 

This chapter provides a demonstration of the crosscall mechanism that is used for communication 

between software objects through the OMS. It contains the following topics: 


l “Example Interface Definition” on page 140 

l “Writing the Crosscall Client” on page 144 

l “Writing the Crosscall Server” on page 152 

Overview 

In this example, the IXA IDL specification defines an agreement between a client 

process and a server process about certain services that will be executed by the server 

on behalf of the client. In this case, the service is a simple database of person objects 

with a name and an age, for which a client can add, modify, or delete entries. The IXA 

IDL compiler maps this definition into OMS-specific calls that perform the required 

service. The compiler generates source files for the server and for the client. 

l 

l 

For the server side, the compiler generates the required mechanisms for receiving 

the call and the invoking the crosscall function, as well as templates for the crosscall 

functions that provide the services. When developing the application, you use 

the template to implement the actual call functions. The server must link all 

generated files and include their headers, so that it contains all of the calling infrastructure, 

in addition to the call function definitions. 

For the client side, the compiler generates stub functions that the client uses to 

make the calls, and provides template callback functions for deferred calls. The 

client must link the stub code and include the headers, and also the implementations 

of the callback functions if there are deferred calls. 


Crosscall Example 139

Example Interface Definition 


The following IXA IDL code defines the Person crosscall interface, which defines a 

data structure to hold information about people (their name and age), and one operation 

of each type to act on that data: 

interface Person 

{ 

struct person_Entry 

{ 

string 

name; 

unsigned short age; 

}; 

}; 

oneway void addPerson(in person_Entry aPerson); 

unsigned short getAge(in string aName); 

deferred boolean deletePerson(in string aName); 

Notice that the getAge operation uses the default twoway invocation type. 

Rather than declaring inout or out parameters, the two-way and deferred operations 

return values, which will be mapped to output parameters during compilation. 

Generated 

Stub Files 

The IXA IDL compiler generates the following _stub_c.h file for the Person interface. 

The generated code declares initialization and termination functions for the client 

side of the interface, and stub functions for each operation defined in the interface. 

The compiler creates a vector table (VMT) that the generated crosscall infrastructure 

uses to access the callback functions for deferred operation. Initially, this table points 

to the generated callback function templates. This stub file defines an accessor function 



#ifndef _OMS_IDL_C_IXA_C_EXAMPLE1_STUB_C_H_ 

#define _OMS_IDL_C_IXA_C_EXAMPLE1_STUB_C_H_ 

#ifdef __cplusplus 

extern "C" 

{ 

#endif /* __cplusplus */ 

#include "ix/asl.h" 

#include "ix/ns.h" 

#include "ix/ossl.h" 

#include "ix/asl/ixbasecc.h" 

/**================================================= 

* Start stub declaration of interface Person 

*================================================*/ 

140 Crosscall Example 



/* Declare the interface name for Person interface */ 

extern const char Person_intName[]; 

/* Declare the local operation names for CC_VMT_Person interface */ 

/* Declare the name for Person::addPerson operation */ 

extern const char Person_addPerson_opName[]; 

/* Declare the name for Person::getAge operation */ 

extern const char Person_getAge_opName[]; 

/* Declare the name for Person::deletePerson operation */ 

extern const char Person_deletePerson_opName[]; 

/* Client initialization function for Person interface */ 

extern ix_error stub_Person_init(ix_base_t* basep, 

ix_cap *capp); 

/* Client finalization function for Person interface */ 

extern ix_error stub_Person_fini(ix_base_t* basep); 

typedef struct 

{ 

char* name; 


} Person_person_Entry; 

/**================================================= 

* Helper functions for Person_person_Entry structure 

*================================================*/ 

/* Marshaling function for Person::person_Entry structure */ 

extern ix_error ix_sds_r_Person_person_Entry (ix_sds aSds, const 

Person_person_Entry* val); 

/* Demarshaling function for Person::person_Entry structure */ 

extern ix_error ix_sds_p_Person_person_Entry (ix_sds aSds, 

Person_person_Entry* val); 

/* Initialization function for Person::person_Entry structure */ 

extern ix_error init_Person_person_Entry (Person_person_Entry* val); 

/* Finalization function for Person::person_Entry structure */ 

extern ix_error fini_Person_person_Entry (Person_person_Entry* val); 

/* Release function for Person::person_Entry structure */ 

extern ix_error release_Person_person_Entry (Person_person_Entry* 

val); 

/**================================================= 

* End helper functions for Person_person_Entry structure 

*================================================*/ 

Crosscall Example 141 



/* Declare the a cross call function pointer type for 

Person::addPerson operation */ 

typedef ix_error (* Person_addPerson_fptr)(ix_base_t* basep, const 

Person_person_Entry* aPerson); 

/* Declare the crosscall reference function for Person::addPerson 

operation */ 

extern ix_error stub_Person_addPerson(ix_base_t* basep, const 

Person_person_Entry* aPerson); 

/* Declare the a cross call function pointer type for Person::getAge 

operation */ 

typedef ix_error (* Person_getAge_fptr)(ix_base_t* basep, const 

char* aName, unsigned short* _return_val); 

/* Declare the crosscall reference function for Person::getAge 

operation */ 

extern ix_error stub_Person_getAge(ix_base_t* basep, const char* 

aName, unsigned short* _return_val); 

/* Declare the a cross call function pointer type for 

Person::deletePerson operation */ 

typedef ix_error (* Person_deletePerson_fptr)(ix_base_t* basep, 

const char* aName, int* _return_val); 

/* Declare the crosscall reference function for Person::deletePerson 

operation */ 

extern ix_error stub_Person_deletePerson(ix_base_t* basep, const 

char* aName); 

/* Declare the deffered callback function for Person::deletePerson 

operation */ 

extern ix_error deferred_cb_Person_deletePerson (ix_error anError, 

void* cookie, ix_sds aSds); 

/* Declare the callback function pointer type for 

Person::deletePerson operation */ 

typedef ix_error (* Person_deletePerson_cb_fptr)( ix_base_t* basep, 

ix_error anError, int _return_val); 

/* Declare the crosscall VMT structure for Person interface */ 

/************** 

** CC_VMT_Person structure holds function pointers 

** to implementation functions for all local 

** and inherited operations 

***************/ 

typedef struct _CC_VMT_Person 

{ 

Person_addPerson_fptr _pCC_Person_addPerson; 

Person_getAge_fptr _pCC_Person_getAge; 

Person_deletePerson_fptr _pCC_Person_deletePerson; 

} CC_VMT_Person; 

/* Declare the callback VMT structure for Person interface */ 




/************** 

** CB_VMT_Person structure holds function pointers to callback 

** functions for all local and inherited operations 

****************/ 

typedef struct _CB_VMT_Person 

{ 

Person_deletePerson_cb_fptr _pCB_Person_deletePerson; 

} CB_VMT_Person; 

/* Accessor function for callback VMT */ 

extern ix_error getCBVMT_Person(ix_base_t* basep, 

CB_VMT_Person** pInterfaceCBVMT); 

/**================================================= 

* End stub declaration of interface Person 

*================================================*/ 


} 


#endif /* end define */ 

Generated 

Skeleton Files 

The IXA IDL compiler generates the following _sk_c.h file for the Person interface, 

which the server code includes. 

The generated code declares initialization and termination functions for the server 

side of the interface, and invocation functions for each operation defined in the interface. 

The compiler creates a vector table (VMT) that the generated crosscall infrastructure 

uses to access the invocation functions. Initially, this table points to the 

generated crosscall function templates. The skeleton file defines an accessor function 




extern "C" 

{ 


#include "ixa_c_example1_stub_c.h" 

/**================================================= 

* Start skeleton declaration of interface Person 

*================================================*/ 

/* Server initialization function for Person interface */ 

extern ix_error sk_Person_init (ix_base_t* basep, ix_cap* capp); 

/* Server finalization function for Person interface */ 

extern ix_error sk_Person_fini (ix_base_t* basep); 

/* Accessor function for crosscall VMT */ 

extern ix_error getCCVMT_Person(ix_base_t* basep, 



Writing the Crosscall Client 

CC_VMT_Person** pInterfaceCCVMT); 

/* Declare the invoke function for Person::addPerson operation */ 

extern ix_error invoke_Person_addPerson(ix_base_t* basep, ix_sds 

anSds, idl_ixa_c_crossCall_fptr pFunc); 

/* Declare the invoke function for Person::getAge operation */ 

extern ix_error invoke_Person_getAge(ix_base_t* basep, ix_sds anSds, 

idl_ixa_c_crossCall_fptr pFunc); 

/* Declare the invoke function for Person::deletePerson operation */ 

extern ix_error invoke_Person_deletePerson(ix_base_t* basep, ix_sds 

anSds, idl_ixa_c_crossCall_fptr pFunc); 

/**================================================= 

* End skeleton declaration of interface Person 

*================================================*/ 


} 


#endif /* end define */ 


The client program adds a new person, retrieves the age of the same person, then 

deletes the entry it has added, using the defined crosscalls. The following code establishes 

a connection to the server and initializes the crosscall interface, than calls the 

generated stub functions and handles the returned values. Finally, it terminates the 

crosscall connection and cleans up allocated space. 

This file defines an initialization function, idl_client_init, that takes command 

line arguments (argc and argv): 

l 

l 

The first argument is the name of the crosscall server to which to connect. 

The second argument is command, one of the strings ADD, DEL, or AGE. 

— "ADD" must be followed by two more arguments, a name and a number for 

the age. The program will add the specified person. 

— "DEL" or "AGE" must be followed by one more argument, a name. The 

program will delete or retrieve the name of the specified person. 

The initialization also changes the callback pointer for the deferred operation from 

the generated template function to the application-defined callback function. 

//Crosscall client for Person interface 

#include 

#include 

#include 

#include 

#include "person_stub_c.h" 

#include "person_cb_c.h" 




static ix_task* _p_idl_ixa_c_clientTestTask = 0; 

static ix_cap* _p_idl_ixa_c_clientTestCap = 0; 

static ix_ossl_thread_t _Thread = 0; 

static ix_base_t* pToken = 0; 

static int responseReceived = 0; 

ix_error our_Person_deletePerson_cb(ix_base_t* basep, 

ix_error anError, int _return_int); 

static ix_error idl_thread_run(void* cookie, void** dummy) 

{ 


(void)dummy; 


fprintf(stderr,"Communication thread started!\n"); 

err = ix_cap_loop((ix_cap*)cookie); 

if((err != 0) && !ix_error_is(err, 0, IX_ERROR_STOP)) 

ix_error_dump(stderr,err); 

return err; 

} 

//Callback function for deferred op, based on generated template 

ix_error our_Person_deletePerson_cb (ix_base_t* basep, 

ix_error anError, int _return_int) 

{ 


"our_Person_deletePerson_cb"; 


(void)basep; 

if(anError) 

{ 

responseReceived = 1; 

return anError; 

} 

if(_return_int >= 0) 

fprintf(stderr, "%s - deletePerson operation has been 

successful!\n", localFunctionName); 

else 

fprintf(stderr, "%s - deletePerson operation failed!\n", 


} 

responseReceived = 1; 

return err; 

static ix_error idl_client_init(int argc, char** argv) 

{ 

static char localFunctionName[]="idl_client_init"; 


CB_VMT_Person* pCBVMT = 0; 

int aResult = 0; 

ix_error threadError = 0; 




void* context; 

if (argc


} 


memset(pToken,0,sizeof(ix_base_t));//init token memory 

//call generated interface initialization function 

err = stub_Person_init (pToken, _p_idl_ixa_c_clientTestCap); 

if(err) 

{ 

err = ix_error_new(0,0,err, 

"%s :: stub_Person_init failed!\n", 



} 

err = ix_oms_connect(pToken, argv[1]);//connect to server 

if (err) 

{ 


"%s - ix_oms_connect failed!\n", 



}; 

err = ix_oms_wait_connected(pToken); 

if (err) 

{ 


"%s - ix_oms_wait_connected failed!\n", 



}; 

//Specify the externally defined callback function 

err = getCBVMT_Person(pToken, &pCBVMT); 

if(err) 

{ 


" getCBVMT_Person function failed!\n"); 


} 

pCBVMT->_pCB_Person_deletePerson = 

our_Person_deletePerson_cb; 

return err; 

err_label1: 

/* Shutdown */ 

/* signal the cap to clean-up and exit */ 

err = ix_cap_shutdown(_p_idl_ixa_c_clientTestCap, &aResult); 

if(err || aResult) 

{ 


"%s - ix_cap_shutdown failed!\n", 





}; 

err = ix_ossl_wait_for_thread(_Thread, &threadError, 

&context); 

ix_ossl_kill_thread(_Thread); 

if(_p_idl_ixa_c_clientTestTask!=0) 

{ 

ix_error err1 = 0; 

err1 = ix_task_fini(_p_idl_ixa_c_clientTestTask); 

if (err1) 

{ 


"%s - ix_task_fini failed!\n", 


}; 

free(_p_idl_ixa_c_clientTestTask); 

_p_idl_ixa_c_clientTestTask = 0; 

_p_idl_ixa_c_clientTestCap = 0; 

} 

if(pToken!=0) 

{ 

free(pToken); 

pToken = 0; 

} 

} 

return err; 

static ix_error idl_client_fini(void) //clean up 

{ 

static char localFunctionName[]="idl_client_fini"; 


int aResult = 0; 

ix_error threadError = 0; 

void* context; 

err = ix_oms_disconnect(pToken);//disconnect from server 

if (err) 

{ 


"%s - ix_oms_disconnect failed!\n", 



} 

err = ix_oms_wait_disconnected(pToken); 

if (err) 

{ 


"%s - ix_oms_wait_disconnected failed!\n", 



} 




err = stub_Person_fini (pToken);// interface termination fn 

if (err) 

{ 


"%s - stub_Person_fini failed!\n", 



} 

err_label1: 

/* Shutdown */ 

/* signal the cap to clean-up and exit */ 

err = ix_cap_shutdown(_p_idl_ixa_c_clientTestCap, &aResult); 

if(err || aResult) 

{ 


"%s - ix_cap_shutdown failed!\n", 


goto thread_shutdown; 

}; 

err = ix_ossl_wait_for_thread(_Thread, &threadError, 

&context); 

thread_shutdown: 

ix_ossl_kill_thread(_Thread); 

if(_p_idl_ixa_c_clientTestTask!=0) 

{ 


err1 = ix_task_fini(_p_idl_ixa_c_clientTestTask); 

if (err1) 

{ 


"%s - ix_task_fini failed!\n", 


}; 

free(_p_idl_ixa_c_clientTestTask); 

}; 

} 

return err; 

static ix_error addPerson(const char* aName, 

unsigned short anAge) 

{ 

static char localFunctionName[]="addPerson"; 


Person_person_Entry anEntry; 

err = init_Person_person_Entry(&anEntry); 

if (err) 

{ 


"%s - init_Person_person_Entry failed!\n", 






}; 

anEntry.name = strdup(aName); 

anEntry.age = anAge; 

//call generated stub function 

err = stub_Person_addPerson(pToken,&anEntry); 

if (err) 

{ 


"%s - stub_Person_addPerson failed!\n", 



}; 

fprintf(stderr, "%s added to the database!\n", 

aName); 

err_label1: 

{ 


err1 = fini_Person_person_Entry(&anEntry); 

if (err1) 

{ 

err = ix_error_new(0,0,err1, 

"%s - fini_Person_person_Entry failed!\n", 


} 

} 

return err; 

} 

static ix_error getAge (const char* aName, 

unsigned short* anAge) 

{ 

static char localFunctionName[]="getAge"; 



err = stub_Person_getAge (pToken, aName, anAge); 

if (err) 

{ 


"%s - stub_Person_getAge failed!\n", 



} 

if(*anAge == 0) 

fprintf(stderr, "%s is not in the database!\n",aName); 

else 

fprintf(stderr, "%s is %hu years old!\n",aName, *anAge); 




err_label1: 

} 

return err; 

static ix_error deletePerson(const char* aName) 

{ 

static char localFunctionName[]="deletePerson"; 



err = stub_Person_deletePerson(pToken,aName); 

if (err) 

{ 


"%s - stub_Person_deletePerson failed!\n", 



} 

/* Wait to receive the callback response */ 

while(!responseReceived) 

{ 

sleep(1); 

} 

err_label1: 

return err; 

} 

static void idl_client_cleanup(ix_error anError) 

{ 

if (anError) 

ix_error_dump(stderr,anError); 

ix_error_fini(); 

} 

int main(int argc, char** argv) 

{ 

int exitStatus = 0; 



err = idl_client_init(argc, argv); 

if (err) 

{ 

exitStatus = -1; 

goto err_label_1; 

} 

if(strcmp(argv[2],"ADD") == 0) 

{ 

unsigned short age = 1; 

if(argc>4) 



Writing the Crosscall Server 

age = atoi(argv[4]); 

err = addPerson(argv[3],age); 

if (err) 

{ 



}; 

} 

else if(strcmp(argv[2],"DEL") == 0) 

{ 

err = deletePerson(argv[3]); 

if (err) 

{ 



} 

} 

else if(strcmp(argv[2],"AGE") == 0) 

{ 


err = getAge(argv[3],&age); 

if (err) 

{ 



} 

} 

else 

{ 

fprintf(stderr, "Invalid command!\n"); 



} 

err_label_1: 

err = idl_client_fini(); 

if (err) 

{ 


idl_client_cleanup(err); 

} 

idl_client_cleanup(err); 

} 

return exitStatus; 


The crosscall server implements the crosscall operations, basing them on the template 

functions provided by the IXA IDL compiler. In this example, the server is an ACE, 

so it also defines the standard ACE initialization and termination functions, ix_init 

and ix_fini. 




This example creates a database of persons, building a double linked list (sorted by 

name) in which to keep all the entries received from clients. It implements the three 

operations by adding the new entries to the list, deleting them or getting the person’s 

age if it is in the list. 

It then uses the generated VMT accessor to change the vector table to point to the 

correct implementation functions (rather than the default, the generated template 

functions). Using this technique, different servers that implement the same interface 

in the same process can have different behavior. You could also change the behavior 

at run time, based on an external trigger, by changing the vector table to point to 

different function implementations. 

The server code uses the generated initialization function from the 

skeleton to initialize the server side of the crosscall connection, 

and uses the generated termination function to terminate the 

connection and free resources. 

#include 

#include 

#include 

#include "person_sk_c.h" 

#include "person_cc_c.h" 

int addPersonEntry(const char* name, unsigned short age); 

int getPersonsAge(const char* name,unsigned short* pAge); 

int deletePersonEntry(const char* name); 

ix_error our_Person_addPerson(ix_base_t* basep, 

const Person_person_Entry* aPerson); 

ix_error our_Person_getAge(ix_base_t* basep, const char* aName, 

unsigned short* _return_val); 

ix_error our_Person_deletePerson(ix_base_t* basep, 

const char* aName, int* _return_val); 

int removeEntries(void); 

typedef struct _PersonEntry PersonEntry; 

/*********************************************************** 

** Data structure and helper functions for manipulating it 

************************************************************/ 

struct _PersonEntry 

{ 

const char* name; 


PersonEntry* next; 

PersonEntry* prev; 

}; 

static PersonEntry* _personList = 0; 

int addPersonEntry(const char* name, unsigned short age) 

{ 

PersonEntry* pEntry = _personList; 

PersonEntry* pPrevEntry = 0; 

PersonEntry* pNewEntry = 0; 

int res = 0; 




} 

int pos; 

for(pos = 0; pEntry != 0; pEntry = pEntry->next, pos++) 

{ 

res = strcmp(pEntry->name,name); 

if(res == 0) 

return -1; 

else if(res < 0) 

{ 

pPrevEntry = pEntry; 

continue; 

} 

else 

break; 

} 

pNewEntry = malloc(sizeof(PersonEntry)); 

if(pNewEntry == 0) 

return -2; 

memset(pNewEntry,0,sizeof(PersonEntry)); 

pNewEntry->name = strdup(name); 

pNewEntry->age = age; 

if(pos == 0) 

{ 

pNewEntry->next = _personList; 

if(_personList != 0) 

_personList->prev = pNewEntry; 

_personList = pNewEntry; 

} 

else 

{ 

if(pEntry == 0) 

{ 

pNewEntry->prev = pPrevEntry; 

pPrevEntry->next = pNewEntry; 

} 

else 

{ 

pNewEntry->next = pEntry; 

pNewEntry->prev = pEntry->prev; 

pEntry->prev = pNewEntry; 

if(pNewEntry->prev != 0) 

pNewEntry->prev->next = pNewEntry; 

} 

} 

return pos; 

int getPersonsAge(const char* name,unsigned short* pAge) 

{ 


int pos; 

int res; 

*pAge = 0; 


{ 





} 

if(res == 0) 

{ 

*pAge = pEntry->age; 

return pos; 

} 

else if(res > 0) 

return -1; 

}; 

return -1; 

int deletePersonEntry(const char* name) 

{ 


int res = 0; 

int pos; 


{ 


if(res == 0) 

{ 

if(pEntry->prev != 0) 

pEntry->prev->next = pEntry->next; 

else 

_personList = pEntry->next; 

if(pEntry->next != 0) 

pEntry->next->prev = pEntry->prev; 

free(pEntry); 

return pos; 

} 

else if(res < 0) 

continue; 

else 

break; 

}; 

return -1; 

} 

int removeEntries() 

{ 


for(; _personList != 0; pEntry = _personList) 

{ 

_personList = _personList->next; 

free(pEntry); 

}; 

return 0; 

} 

static ix_base_t* pToken = 0; 

/************************************ 

** Definition of crosscall template function for 

** Person::addPerson operation 

**************************************/ 




ix_error our_Person_addPerson(ix_base_t* basep, 

const Person_person_Entry* aPerson) 

{ 


"our_Person_addPerson"; 


(void) basep; 

if(addPersonEntry(aPerson->name,aPerson->age) < 0) 

fprintf(stderr, "%s - addPersonEntry failed!\n", 


} 

return err; 

/************************************ 


** Person::getAge operation 

***************************************/ 

ix_error our_Person_getAge (ix_base_t* basep, 

const char* aName, 

unsigned short* _return_val) 

{ 

static const char localFunctionName[] = "our_Person_getAge"; 


(void) basep; 

if(getPersonsAge(aName, _return_val) < 0) 

fprintf(stderr, "%s - getPersonsAge failed!\n", 


} 

return err; 

/************************************ 


** Person::deletePerson operation 

***********************************/ 

ix_error our_Person_deletePerson(ix_base_t* basep, 

const char* aName, 

int* _return_val) 

{ 


"Person_deletePerson"; 


(void) basep; 

*_return_val = deletePersonEntry(aName); 

if(*_return_val < 0) 

fprintf(stderr, "%s - deletePersonEntry failed!\n", 


return err; 




} 

/************************************ 

** ACE initialization 

***********************************/ 

ix_error ix_init(int argc, char** argv, ix_ace** acepp) 

{ 

static char localFunctionName[] = "ix_init"; 


ix_ace* pAce = 0; 

ix_cap* capp = 0; 

CC_VMT_Person* pCCVMT = 0; 

if (argc


/* Initialize the token for the Person interface */ 

err = sk_Person_init (pToken, capp); 

if(err) 

{ 


"%s - Token initialization failed!\n", 



}; 

/* Retrieve the cross call VMT */ 

err = getCCVMT_Person(pToken, &pCCVMT); 

if(err) 

{ 


"%s :: getCCVMT_Person failed!\n", 



}; 

/* Point crosscall vectors to implemented functions */ 

pCCVMT->_pCC_Person_addPerson = our_Person_addPerson; 

pCCVMT->_pCC_Person_getAge = our_Person_getAge; 

pCCVMT->_pCC_Person_deletePerson = our_Person_deletePerson; 

*acepp = pAce; 

fprintf(stderr,"%s: ace communication is initialized!\n", 


return err; 

err_label1: 

if(pAce != 0) 

{ 

/* Finalize the ix_ace structure*/ 

err = ix_ace_fini(pAce); 

if (err) 

{ 

err = ix_error_new(IX_ERROR_LEVEL_LOCAL, 

IX_ERROR_NULL, err, 

"%s: ix_ace_fini failed!\n", localFunctionName); 

}; 

} 

free(pAce); 

pAce = 0; 

}; 

if(pToken != 0) 

{ 

free(pToken); 

pToken = 0; 

}; 

return err; 




// ACE termination 

ix_error ix_fini(int argc, char** argv, ix_ace* pAce) 

{ 

static char localFunctionName[]="ix_fini"; 


(void) argc; 

(void) argv; 

err = sk_Person_fini (pToken); 

if (err) 

{ 

err = ix_error_new(0, 0, err, 

"%s: Token finalization failed!\n", 



}; 

/* Cleanup the _personList */ 

removeEntries(); 

err_label1: 

/* Free the ix_ace structure */ 

if (pAce != 0) 

{ 

/* Finalize the ix_ace structure*/ 


if (err) 

{ 



"%s: ix_ace_fini failed!\n", 


}; 

free(pAce); 

} 

free(pAce); 

/* Free the token structure */ 


free(pToken); 

} 

fprintf(stderr, "%s: ix_fini called. Cleaned up!\n", 


return err; 

Terminating 

the Server 

The following code defines a clean termination for the interface in the server. 

static char localFunctionName[]="ix_fini"; 


(void) argc; 

(void) argv; 




/* Call the generated termination function */ 

err = sk_Person_fini (pToken); 

if (err) 

{ 

err = ix_error_new(0, 0, err, 

"%s: Token finalization failed!\n", 



}; 

/* Clean up the _personList */ 

removeEntries(); 

err_label1: 

/* Free the ix_ace structure */ 

if (pAce != 0) 

{ 

/* Terminate the ACE */ 


if (err) 

{ 



"%s: ix_ace_fini failed!\n", 


}; 

free(pAce); 

} 

/* Free the token structure */ 


free(pToken); 

fprintf(stderr, "%s: ix_fini called. Cleaned up!\n", 


return err; 



Chapter 13 

Using Sets of Data to Classify Packets 

This chapter describes sets and searches, which you can use to classify packets based 

on their contents; that is, the values of fields. Sets are an efficient way to track a large 

number of classes of packets. 


l “Overview of Sets and Searches” on page 161 

l “When to Use Sets” on page 162 

l “Defining Sets and Searches” on page 162 

l “How to Use Sets and Searches” on page 167 

Overview of Sets and Searches 

You can define data tables called sets that associate any arbitrary application-defined 

data with packets. For each set, you define one or more named searches that determine 

whether the current packet has a matching element in the set, based on the values of 

specified fields. 

A set is a collection of elements where each element has a header of one or more keys, 

and contains a pointer to any arbitrary data that you define. A search matches the key 

values in the header with the values of specific fields in an incoming packet. When 

all the values match, you can take an action with regard to the matching element; for 

example, add to a counter, or access and save another field value in the packet. 

When a search does not match any element with the incoming packet, you have the 

option of adding a new element to the set. 


Using Sets of Data to Classify Packets 161

When to Use Sets 

When to Use Sets 

You use sets to define collections of packets that are associated with each other by 

virtue of their contents. They allow you to keep state information for all packets that 

have the same values in specific fields. If you want to form collections on structural 

criteria, such as “the set of all packets with IP header lengths greater than twenty 

bytes,” use a classification predicate rather than a searchable set. 

You can take any kind of action you want as a result of the set classification. For 

example, you can count packets going to or from each address, keeping the counters 

as set data. You can set targets for packets based on their set membership, add 

members to or delete members from the set, or create messages from the packets or 

the set data and pass them to other ACEs or programs using crosscalls. 

You can use sets to associate application data with packets. For example, you can 

initialize a set with a list of interesting addresses, in order to classify all packets that 

come from or go to those addresses. One search might compare the ip.src field of 

packets to the elements of the set, to identify any packets that come from one of the 

addresses. Another search could compare the ip.dest field to the addresses, to identify 

packets that are going to them. 

You can also use sets to collect new data about packet flow. For example, you can start 

with an empty set, and, for each incoming packet that does not already have a 

matching set element, create a new set element using its ip.src value, and add it to 

the set. When an incoming packet does match, you can increment a counter in the 

matching element. In this way, you can keep track of the sources of all packets coming 

through the ACE. 

Defining Sets and Searches 

Use NCL to declare the name and suggest the size of a set, and to define the searches 

that evaluate set membership. Declare a corresponding C structures for the set in the 

ACE initialization code. You modify the contents of sets using actions. See “Initializing 

and Populating Sets” on page 165. 

Defining Sets 

in NCL 

Use the set keyword to declare, name, and define a set in NCL. You provide the 

number of keys, and suggest a size for the set. For each set, you can define any 

number of searches, using the search keyword. Each search is associated with one 

and only one set, and you name it using the form setname.searchname. You specify 

a requires clause in the search. If this Boolean expression succeeds, the search is 

executed, and if it fails the search is not executed. 

Each search definition specifies the exact number of keys that you specified for the 

set, and associates each key with a protocol field. When the search is executed, the 

ACE runtime compares the value of the specified protocol field in the current packet 

to the value of the corresponding key for each element in the set. If all of the field 

values in the packet match the key values in an element, the search succeeds, and 

keeps a pointer to the matching element. 

162 Using Sets of Data to Classify Packets 



You can use a search in a rule or an action, referring to it by the name, 

setname.searchname. When you refer to it by name, you are actually referring to 

the result of the search, which the ACE runtime obtains when it parses the search 

definition for an incoming packet. A search can have one of the following results: 

l 

l 

l 

The search did not run because the requirements were not met. 

The search ran and found a matching element. 

The search ran and did not find a matching element. 

Example 

The following NCL example defines a set named setIP that has 2 keys, and two 

searches in that set that compare each of the keys to fields in the IP protocol. The 

searches are only executed for IP packets. 

l 

l 

The search setIP.key1 identifies a set element where the first key matches an IP 

packet’s destination address (the field ip.dst). 

The search setIP.key2 identifies a set element where the second key matches an 

IP packet’s source address (the field ip.src). 

Rules invoke one of two action functions, passing additional values as required by 

the action definition, including the search used. 

l 

l 

When a matching element is found for either key, the action increments a counter 

in the element. 

When no matching element is found for either key, the action inserts an element 

into the set to match the current packet. 

// 

// A simple application to count the packets 

// 

// countncl.ncl 

// 

#include "ix_tcpip.ncl" 

Using Sets of Data to Classify Packets 163 



set setIP 

{ 

size_hint { 256 } 

} 

search setIP.key1(ip.dst) 

{ 

requires{ ip } 

} 

search setIP.key2(ip.src) 

{ 

requires{ ip } 

} 

predicate insertDst { ip && (! setIP.key1) } 

predicate insertSrc { ip && (! setIP.key2) } 

rule found1 { setIP.key1 } 

{ incrementSetElement(1, ip.dst, setIP.key1) } 

rule found2 { setIP.key2 } 

{ incrementSetElement(2, ip.src, setIP.key2) } 

rule new3 { insertDst } 

{ insertSetElement(3, ip.dst, setIP.key1) } 

rule new4 { insertSrc } 

{ insertSetElement(4, ip.src, setIP.key2) } 


For more information on defining sets and searches in NCL, see Chapter 6, “Network 

Classification Language (NCL),” in the IXA SDK Reference. 

Defining Sets 

in ASL 

To use the sets and searches that you define in NCL, your ACE initialization code 

must include a header file containing set structure declarations that match the NCL 

definitions. The ACE initialization function must create each set structure using the 

ASL function ix_set_new. 

The set structure is created on initialization of the ACE. A mismatch between the 

NCL and ASL declarations results in a run-time error. 

Action code in the ACE can reuse an existing set structure for another set of the same 

size or smaller by using the function ix_set_init. Again, if the reinitialization does 

not match the set’s NCL declaration, a run-time error results. 

Example 

The following code fragment is part of the ACE initialization code. It extends the 

ACE structure to contain a set, and later creates the set as part of the ACE: 

//extend ACE structure to include set 

struct ace1 

{ 

ix_ace base_ace; 



Initializing and Populating Sets 

ix_set *setp; // creates set when creating the ACE 

} 

... 

// on creation, name setIP links it to the NCL 

ix_set_new (&acep->setp, 1, 256, "setIP", &acep->ace); 


Creating the set structure does not generate any elements with which to populate it. 

You can populate a set with an initial set of elements, then later add or delete 

elements using actions, or you can populate it entirely through actions. 

In the action code for the ACE, define the action functions invoked by the NCL rules 

to retrieve data from a set or place data in a set, based on the results of searches. 

l 

l 

l 

To create an element, use the ASL function ix_element_new, then initialize the 

key values using the function ix_element_init_keys. To associate application 

data with the element, access the ix_element->user_info field directly. 

To insert the new element in a set, use the function ix_set_insert_element, or 

extract the insertion location from the search result, and pass it to the function 

ix_set_insert_at_location. 

To remove the element from the set, use the function ix_set_remove_element or 

ix_set_remove_at_location. 

— You can reuse an element that you have removed from a set by reinitializing 

the keys. 

— You can reuse a removed element in a different set by using the function 

ix_element_init, then reinitializing the keys. 

Example 

The action code for the ACE defines the four action functions invoked by the rules. 

Each action requires three arguments in addition to the two passed automatically. 

The rules pass these additional values to the action on invocation. 

// utility fn to construct print string from search result 

void my_search_result (ix_search *rsltp, char *buf) 

{ 

switch (ix_set_get_search_result (rsltp)) { 

case NOT_RUN: 

sprintf(buf, "ix_search = %p, NOT_RUN", rsltp); 

break; 

case MISS: 

sprintf(buf, "ix_search = %p, MISS", rsltp); 

break; 

case HIT: 

sprintf(buf, "ix_search = %p, HIT", rsltp); 

break; 

default: 

my_error_handler((ix_error) 0, "my_search_result failed."); 

} 

} 


Using Sets of Data to Classify Packets 165


// 

// ACTION FUNCTION DEFINITIONS 

// 

int incrementSetElement (ix_ace *ace, ix_buffer buf, 

int rule, 

int key, 

ix_search *rsltp) 

{ 

ix_element *elemp; 

int *myData; 

char cbuf[128]; 

my_search_result(rsltp, cbuf); 

printf("\t%d) incrementSetElement(%d, 0x%x, %s)\n", 

count, rule, key, cbuf); 

elemp = ix_set_get_element_from_search_obj(rsltp); 

myData = (int*) elemp->user_data; 

*myData += 1; 

} 

return 0; 

int insertSetElement(ix_ace *ace, ix_buffer buf, 

int rule, 

int key, 

ix_search *rsltp) 

{ 

ix_element *elemp; 

ix_error err; 

int *myData; 

char cbuf[128]; 

ace1 *myAce = (ace1*) ace; 

ix_set *setIPp = myAce->setIPp; 

my_search_result(rsltp, cbuf); 

printf("\t%d) insertSetElement(%d, 0x%x, %s)\n", 

count, rule, key, cbuf); 

err = ix_element_new(&elemp, 1); 

if (err) my_error_handler(err, "ix_element_new(&elemp, 1)"); 

err = ix_element_init_keys(elemp, 1, key); 

if (err) my_error_handler(err, 

"ix_element_init_keys(elemp, 1, key)"); 

myData = (int*) malloc(sizeof(int)); 

*myData = 1; 

elemp->user_data = (void*) myData; 



How to Use Sets and Searches 

err = ix_set_insert_at_location(setIPp, rsltp, elemp); 

if (err) my_error_handler(err, 

"ix_set_insert_at_location(setIPp, rsltp, elemp)"); 

} 

return 0; 


For more information on creating and using sets in ASL, see Chapter 4, “The ASL 

Core Support Package API,” in the IXA SDK Reference. 


The ACE runtime executes searches when it runs the classification code for an 

incoming packet. For each incoming packet, the ACE runtime tries every search 

defined in the NCL file. If the requires clause succeeds, the ACE runtime executes 

the search and stores the result in the corresponding ASL set object. 

You can also use the ASL set search functions to initiate a search anywhere in your 

action code. For example, you might want to initiate a search in response to an event 

or a message. 

Using 

Searches in 

Rules 

You can refer to a search by name on either side of a rule. How it is used depends on 

which side of the rule it is on. 

l 

l 

When used on the left side of a rule as part of the predicate, the search name acts 

as a Boolean expression. It succeeds when the search was executed and found a 

matching record in the set. If the search was not executed because the requirements 

were not met, or if it was executed but failed to find a matching element, 

the expression evaluates to FALSE. 

When you pass a search name as an action argument on the right side of a rule, 

the action can use the passed search object to obtain the result of the search (HIT, 

MISS, or NOT_RUN), and either the found element or a location at which to insert a 

new element in the set. 

Using Actions 

to Modify Sets 

When a rule passes a search name to an action, the action function receives a search 

object. This object contains: 

l 

l 

l 

The result of the search, one of the constants HIT, MISS, or NOT_RUN. Use the function 

ix_set_get_search_result to extract this value. 

If the search was successful (that is, the result is HIT), the search object contains 

the found element. 

If the search was unsuccessful (that is, the result is MISS), the search object 

contains a location at which to insert a new element in the set. 

Using Sets of Data to Classify Packets 167 



Use the function ix_set_get_element_from_search_obj to extract the element or 

insertion location. If the search was not run (that is, the result is NOT_RUN), this function 

returns NULL. 

You can take actions based on the fact of a search succeeding or failing, without 

regard for the data portion of the set element. For example, an action can simply set 

the target for the packet based on whether one of the searches succeeds. 

An action function can also modify a set element by changing its associated data. For 

example, when you have identified a packet that is coming from one of the interesting 

addresses, you can increment a counter in the matching element. 

You can look at or copy the data in a matching element, and take actions based on that 

data. For example, after a packet comes in from a particular address and you have 

incremented the counter in the matching element, you can check whether the counter 

has reached a certain value. If it has, you can build a message from it and send it to 

the host application in an upcall. 

An action function can create a new set element, using the search result’s insertion 

location. It can also delete a set element, directly or after a delay. To delay an action 

on an element, make the action function schedule an event, and delete the element in 

the event callback function. 

For more information on set, element, and event manipulation, see Chapter 4, “The 

ASL Core Support Package API,” in the IXA SDK Reference. 

Deleting Sets 

Use the function ix_set_delete to delete a set and all remaining elements. 

To simply remove the set elements without destroying them, use the function 

ix_set_foreach to walk through the set. 



Index 

A 


accelerated 7 

action code part 105 

binding 38 

blocking not allowed in 120, 124 

C structure 5, 106 

classification part 99 

compared to task 124 

conventional vs. accelerated 7 

creating 10, 22 

creating C structures in 106 

defining behavior of 108 

defining packet flow for 48 

initializing 106 

languages for writing 6 

launching 10 

programmatically 46 

with script 38 

library 87 

L2 bridging 91 

L3 forwarder 89 

NAT 94 

packet processing in 5, 99 

packet reception 83 

packet transmission 85 

predefined 7, 87 

rules 101 

stack 88 

targets in 48 

using to receive and transmit packets 48 

utility functions in 109 

what type to use for what task 8 

action code 105 

action functions 108 

callbacks 108 

compiling 30 

utility functions 108 

see also actions, action functions 

action functions 5, 108 

interaction with rules 108 

predefined 109 

return values 108 

syntax 108 

using to create and delete set elements 167 

what they do 110 

see also actions, action code 

Action Services Library, see ASL 

actions 5 

executing 103 

using to direct packets 51 

using to modify sets 167 

using to populate and modify sets 165 

see also action code, action functions 

active computing element, see ACE 

API overview 17 

applications 1 

building blocks 18 

input and output 79 


L3 forwarding 89 

NAT 94 

TCP/IP stack 88 

communicating within 113, 139 

compiling 29 

configuring and starting 35 

deploying 17 

initializing ACEs 10 

linking 29 

organization of 3 

types 1 

argument passing for crosscalls 133 

client side 134 

deferred calls 137 

one-way calls 136 

server side 135 

two-way calls 136 

ASL 17 

contents 106 

creating objects 106 

error codes 24 

predefined action functions in 109 


using for sets and searches 165 

using to write ACE initialization and action code 

105 

writing action code in 105 

asynchronous crosscalls 120, 121, 123 

handling response with callback 121 

specifying timeouts for 122 

Index 169 


B 

bindings 48 

full names of targets 21 

interface ACEs 82 

L3 forwarder ACE targets 90 

setting in configuration file 38 

setting programmatically 49 

stack ACE targets 88 

static 60 

targets 48 

unbound targets 50 

blocking for crosscalls 120, 124 

building blocks 18 

for input and output 79 

for L2 bridging 91 

for L3 forwarding 89 

for network address translation 94 

for TCP/IP stack handling 88 

C 

.c files 30 

C structures in ASL 23 

callbacks 108 

defining 109 

for deferred crosscall operations 109, 117 

for scheduled events 109 

CAP 10 

using for crosscalls 115 

using for OMS session 21 

classification 99 

definition 2 

role of protocol definition 102 

rule evaluation 103 

rules 101 

using rules and protocol definitions 100 

using sets rather than rules 162 

clients, crosscall 114 

communication access process, see CAP 

communication between ACEs and objects 113, 139 

see also crosscalls 

compilers 20 

compiling 32, 33 

action and initialization code 30 

microACEs 32 

NCL 30 

using makefiles 33 

configuration files 35 

samples for library ACEs 39 

configuration scripts 35 

contacting Intel xii 

control plane 4 

conventional ACE, defined 7 

conventions, typographical xi 

core components 7, 55 

in microACE architecture 57 

writing 61 

core processor 14 

memory shared with microengines 65 

creating ACEs 22 

crosscall interfaces 12 

C structure 23 

defining 114, 116 

example definition 140 

initializing and terminating 125 

using to organize operations 117 

crosscall references 114 

crosscalls 12, 113 

and threads 124 

argument directions 122 

deferred operations 120, 121 

callback functions for 117, 121, 123 

defining callback functions 109 

defining operations 118 

example 139 

writing the client 144 

writing the server 152 

full names of 21 

implementing callback functions 117, 130 

implementing operations 116, 130 

initializing the client 125 

example 125 

initializing the server 128 

example 129 

integrating into applications 123 

invoking remotely 130 

example 131 

making and receiving 114 

making two-way calls from ACEs not allowed 120 

naming operations 119 

one-way operations 120 

opening a connection from the client 131 

organizing operations into interfaces 117 

passing arguments 133 

for deferred call 137 

for one-way call 136 

for two-way call 136 

on client side 134 

on server side 135 

skeletons, example 143 

stubs, example 140 

synchronous and asynchronous operations 120 

two-way operations 120 

using stub functions 130 

using to configure input ACE 80 

handling return values 84 

using to configure library ACEs 124 

using to configure microACEs 68 

when to use 115 

customer support xii 

170 Index 


D 

data processing plane 3 

data sets 161 

data structures 161 

for core processor 161 

shared with microengines 65 

default targets 49 

deferred crosscall operations 120, 121, 123 

callback functions for 117, 121 

where callbacks are defined 109 

delaying actions 106 

deploying applications 17 

development environment 14 

development tools 18, 20, 29 

dispatch loop 

controlling packet flow 73 

dispatch loops 71 

application-defined global registers 73 

example 73 

global registers 72 


returning values to 75 

writing 71 

disposing of packets 103 

dl_buffer_handle register 72 

dropping packets 50 

.dwp files 56 

dynamic NAT 94 

E 

elements 161 

adding to sets 167 


deleting from sets 168 

searching for in sets 161 

embedded Linux 14 

embedded operating system 18 

environment variable IXROOT xii 

error codes 24 

event processing 106 

events 23 


using to delay set element removal 168 

example applications 88 

exception handling in microACEs 62 

flagging in microblocks 76 

writing a handler 64 

F 

file types 30 

firewall applications 1 

fragments and NAT 95 

FTP and NAT 95 

G 

gcc compiler 30 

GNU toolchain 30 

H 

handler functions 108 

for asynchronous operations 109 

for microACE exception packets 64 

hardware architecture 14 

hardware configurations 14 

I 

ICMP errors and NAT 95 

.idl files 30 

IDL, see IXA IDL 

in arguments for crosscalls 122 

initialization 10 

of ACEs 22 

of crosscall interfaces 125 

of function pointers for crosscalls 130 

of microACE Resource Manager 58 

of OMS 21 

initialization functions 22 

for ACEs 22, 106 

for microACEs 62 

inout arguments for crosscalls 122 

input ACEs 79, 83 

configuring with crosscalls 80, 83 

handling crosscall return values 84 


logicalMgmt interface 80 

portMgmt interface 80 

installation directory pathname xii 

Intel, contacting xii 

interface ACEs 79 

binding 82 

configuring with crosscalls 80 


input ACE 83 

integrating with your application 80 

naming 82 

output ACE 85 

source code location 81 

starting 82 

interface definition language, see IXA IDL 

interfaces, see network interfaces, ports, or crosscalls, 

crosscall interfaces 

interobject communication 113, 139 

intrusion detection applications 1 

IP addresses, setting for ports 38 

IP masquerade (port translation) NAT 95 

ix_action_default function 109 

IX_EXCEPTION 62 

IXA IDL 18 

Index 171 


syntax 118 

using to define crosscall interfaces 114, 116 

IXA IDL compiler 18, 29 

generated files 116 

IXP 1200 processor 14 

IXP1200 Microengine Development Environment 18 

IXROOT environment variable xii 

ixstart script 35 

ixsys.config file 35 

K 

key point, explanation of xi 

keys, set 162 

associating with protocol fields 162 

definition 161 

L 

L2 bridging library ACE 91 

configuring 94 

packet processing in 92 

sample configuration files 40 

starting 93 

L3 forwarder library ACE 89 

binding targets 90 



starting 90 

languages for ACE development 18, 20 

layer three forwarding 89 

layer two bridging 91 

ld linker 30 

libraries, run-time 18 

library ACEs 87 

defined 7 


L3 forwarder 89 

NAT 94 

sample configurations files 39 

used in example applications 88 

using crosscalls to configure 124 

Linux 14 

development tools 18 

embedded on IXP1200 18 

TCP/IP stack 18, 88 

load balancing (virtual server) NAT 95 

load balancing applications 2 

logicalIfMgmt interface for input ACE 80 

M 

makefiles 33 

management plane 4 

management programs 22 


memory shared between microengines and core 

processor 65 

microACE Resource Manager 13 

microACEs 7, 32 

components and terms 56 

configuring with crosscalls 68 

defining packet flow with dispatch loop 71 

design example 77 

exception handling 62, 76 


launching 38 

library ACEs 87 

loading 58 

macros 18 

microcode image files 38 

processing pipeline 59 

programming model 55 

project files 56 

Resource Manager 17 

terminating 64 

transmitting packets from 75 

writing the core component 61 

microblock groups 68 


microblocks 7, 55, 75 

combining into groups 68 

defining packet flow iwth dispatch loop 71 

determining packet disposition 75 

flagging exceptions 76 


sink 70 

source 69 

transform 70 

types 69 

using to transmit packets 75 

microcode 7 

compiling 58 

development tools 18 

macros for microACEs 18 

using Workbench to edit 56 

microcode images 58 

specifiying files for loading 38 

Microengine Development Environment 18 

microengine toolchain 32 

microengines 14 

memory shared with core processor 65 

threads 37 

N 

Name Server 21 

synchronous and asynchronous sessions 124 

named searches 162 

naming and referencing OMS objects 21 

172 Index 


NAT library ACEs 94 

binding targets 97 


handling of FTP, fragments, and ICMP 95 

packet processing in 94 


starting 96 

NCL 18, 99 

compiling 30 

using to declare sets 162–164 

using to define sets and searches 100 

NCL compiler 18, 29 

.ncl files 30 

nclcomp compiler 29 

network address translation (NAT) 94 

Network Classification Language, see NCL 169 

network interfaces 2 


receiving and transmitting on with interface ACEs 

79 

see also ports 

note, explanation of xi 

O 

.o files 30 

Object Management System, see OMS 

objects 23 

creating in ACE 106 

in an IXA application 23 

naming 21 

OMS 10 

Name Server 21 

Resolver 20 

services 17 

synchronous and asynchronous entry points 124 

one-way crosscall operations 120 

out arguments for crosscalls 122 

output ACEs 79, 85 


output ports for packets 75 

P 

packet flow 48 

defining with dispatch loops 71 

defining with targets 48 

monitoring with sets 162 

through microACEs 73 

packets 2 

associating with data using sets 162 

classification by ACEs 99 

classification overview 2 

defining traffic flow 11 

through microACEs 59 

with targets 47 

directing to a target 51 

disposing of 103 

dropping 50 

forcing serial processing of 51 

handling with TCP/IP stack 88 

receiving 83 

receiving and transmitting with interface ACEs 79 

role of protocol definitions in classifying 102 

sets of 100 

setting output port 75 

targets as destinations for 48 

transferring with crosscalls vs. targets 115 

transmitting 85 

transmitting from microblocks 75 

using an ACE to receive and transmit 48 

using set searches to check addresses of 104 

populating sets 165 

port translation (IP masquerade) NAT 95 

portMgmt interface for input ACE 80 

ports 2 

configuring 35, 38 

enabling and disabling 84 

IP addresses 85 

MAC address 84 

managing logical configuration 85 

managing physical configuration 84 

receiving and transmitting on with interface ACEs 

79 

statistics 84 

predicates 100 

contents 101 

evaluating 103 

processing pipeline in microACEs 59 

programming interface overview 17 

project file, Workbench 56 

protocol definitions 102 

definition 100 

role in packet classification 102 

TCP/IP 102 

using to classify packets 100 

protocol fields 100 

associating with keys 162 

Q 

quality of service (QoS) applications 2 

R 

receiving packets 83 

reference, explanation of xi 

remote calls 114 

remote procedure invocation 113 

synchronous and asynchronous 120 

Index 173 


Resolver 20 

communicating with 22 

synchronous and asynchronous sessions 124 

Resource Manager 13, 17 

API for memory management 66 




for action functions 108 

for API functions 24 

for crosscalls 122 

RMON statistical monitoring applications 1 

rules 5, 99 

action functions in 101 

components of 101 

definition 100, 101 

evaluating 103 

predicates 101 

using instead of sets 162 

using set searches in 167 

using to trigger actions 100 

what they do 104 

running applications 35 

run-time libraries 18 

S 

.s files 30 

sample applications 88 

scheduled event callbacks 109 

scripts, startup and configuration 35 

SDK components 17 

system software 18 

SDKinstallpath meaning xii 

searches in sets 162 

and rules 100 

ASL code requirements 165 

defining 162 

how to use 167–168 

overview 161 

results 163 

using in rules 167 

using to check incoming packet addresses 104 

serial processing of packets 51 

servers, crosscall 114 

set elements, see elements 169 

set keys 162 

associating with protocol fields 162 

sets 161 

and rules 100 

ASL code requirements 165 


creating and deleting elements using action 

functions 167 

declaring using NCL 162–164 

defining 162 

delaying actions on elements 168 

deleting 168 

how to use 167–168 

overview 161 

populating 165 

using actions to modify 165, 167 

using to associate data with packets 162 

using to classify packets 162 

using to collect data about packet flow 162 

using to keep tables of addresses 104 

when to use 162 

shared memory, microengines and core processor 65 

sink microblocks 70 

skeletons, generated for crosscalls 116 

software development tools 18, 29 

source microblocks 69 

stack ACE 87, 88 

defined 9 

starting and configuring 88 

stack, TCP/IP for Linux 18 

starting applications 35 

startup scripts 35 

static bindings 60 

static NAT 94 

statistical monitoring (RMON) applications 1 

structures for ACE programming framework 23 

creating in ACE 106 

stub files, example 140 

stub functions 114 

generated source files 117 

using to invoke crosscalls 130 

support for Intel xii 

symbols xi 

synchronous and asynchronous crosscalls 120 

synchronous crosscalls 120 

system ACEs 7 

interface 79 

stack ACE 88 

system configuration file 37 

system software 18 

OMS 10 

Resource Manager 13 

starting 35 

T 

tao_idl compiler 29 

targets 11, 50 

and packet flow 47 

binding 48 

binding in configuration file 38 


creating 50 

default 49 

defining 50 

directing packets to 51 

174 Index 


full names of 21 

L3 forwarder ACE 90 

overview 11 

stack ACE 88 

unbound 50 

vs. crosscalls, transferring packets with 115 

tasks 10 

compared to ACE 124 

defined in OMS 10 

using with crosscalls 115, 124 

TCP fragments and NAT 95 

TCP/IP protocol definition for NCL 102 

TCP/IP stack, Linux 18, 88 

termination functions 22 

for ACEs 22 

for crosscall interfaces 125 

for microACEs 64 

threads 37 

and crosscalls 124 

on microengines 8, 37 

timeouts for asynchronous crosscalls 122 

times and events 23 

toolchains 20 

tools for developers 18, 29 

traffic flow 11 

through ACEs 11 

through microACEs 59, 73 

through targets 47 

transform microblocks 70 

transmitting packets 85 

two-way crosscall operations 120 

typographical conventions xi 

U 

unbound targets 50 

.uof files 58 

user ACEs 7 

utility functions in ACEs 109 

V 

variable IXROOT xii 

virtual method table (VMT) 130 

for callback implementations 117, 130 

for crosscall implementations 116, 130 

virtual private networks (VPN) 1 

virtual server (load balancing) NAT 95 

voice over IP (VOIP) applications 2 

WXYZ 

warning, explanation of xi 

Workbench 56 

project files 56 

Index 175 


176 Index 



177

Intel Corporation 

2200 Mission College Blvd. 

PO Box 58119 

Santa Clara, CA 95052-8119 USA 

Tel: 800.628.8686 

www.intel.com

Intel IXA SDK ACE Programming Framework - Department of ...

Create successful ePaper yourself

Delete template?

Save as template?