Writing XIA Applications

TODO: New intro.

Table of Contents XIA Socket API API Documentation Configuration DAG Manipulation RE Format DAG Format DAG Manipulation Library Annotated Examples

XIA Socket API

The Xsockets API was designed to be as similar as possible to the standard socket library to make porting applications easier. It provides 4 socket types:

• XSOCK_STREAM: similar to TCP style sockets
• XSOCK_DGRAM: similar to UDP style sockets
• XSOCK_RAW: similar to the raw sockets used in ping and traceroute
• XSOCK_CHUNK: a new socket type used for content such as video

Differences from standard sockets

• Naming and Addressing: XIA does not use IP addresses, it instead uses [Directed] to specify destinations. TODO we need a link to a description of DAGs, HIDs, ADs, etc...
• The Xsockets API does not implement non-blocking sockets in the current release. However, because the xsocket identifier is a standard socket, the normal poll and select functions can be used to provide similar behavior.

API Documentation

• C/C++ API Documentation
• Python API Documentation

Configuration

Since you can use Click to run multiple virtual nodes on one machine, how does an application know which of potentially many virtual hosts it is running on? Each application must tell the socket API which Click host it is logically part of. To accomplish this, each virtual host has an IP address; the socket API opens a "fake" socket with the IP address of its virtual host which it uses to send and receive data from Click.

A Click host or router is assigned its fake IP address in the Click configuration file. For example, in the stock local topology file included in the XIA distribution, host0 has IP 172.0.0.2 (there is actually a second IP address, 172.0.0.1, used by Click to send messages back to the socket API).

host0 :: XIAInstrumentedEndHost (RE AD0 HID0, HID0, fake0, 172.0.0.2, 172.0.0.1, 11:11:11:11:11:11, 0, aa:aa:aa:aa:aa:aa);

The API is made aware of these addresses via an XIA socket configuration file, typically named xsockconf.ini. Here's a portion of one:

[echoclient]
api_addr=192.0.0.1
click_dataaddr=192.0.0.2
click_controladdr=192.0.0.2

[echoserver]
api_addr=172.0.0.1
click_dataaddr=172.0.0.2
click_controladdr=172.0.0.2

By default, the socket API looks for a file named xsockconf.ini in the current directory; within that file, it looks for a section with the same name as the current executable. To specify a custom file or section, use the set_conf function.

DAG Manipulation

The XIA socket API calls take DAGs in one of two string formats: DAG and RE. Since constructing these strings for all but the simplest DAGs is moderately painful, we've also created DAG manipulation library to simplify the task.

Sometimes it's helpful to be able to see a visual representation of a DAG; to this end, we've created a DAG visualization tool.

RE Format

The RE format is simple and relatively easy to use but cannot represent all DAGs. An RE string consists of the characters "RE " followed by a chain of XIDs, each of which can optionally have a fallback path from the previous node in the chain to itself. Nodes are separated by spaces and parens are used to mark fallback paths. The "start" node is implicit and does not appear in the string. For example:

RE AD:1000000000000000000000000000000000000000 HID:0000000000000000000000000000000000000000 SID:1110000000000000000000000000000000001113
RE ( AD:1000000000000000000000000000000000000000 HID:0000000000000000000000000000000000000000 ) SID:1110000000000000000000000000000000001113

TODO: show example pictures

DAG Format

The DAG format is capable of encoding arbitrary graphs but is more tedious to construct manually. A DAG string is a list of XIDs and their outgoing edges separated by the '-' character; by convention, we use "- \n" as the separator to make DAG strings easier to read when printed. Nodes are implicitly numbered starting from 0. This index is used by other nodes to denote an outgoing edge to a node. A DAG string begins with the characters "DAG " and is followed by the start node's outgoing edges (separated by spaces). This is followed by the list of XIDs and their outgoing edges.

An example may help clarify:

DAG 2 0 - 
AD:4349445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f 2 1 - 
HID:4849445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f 2 - 
SID:534944305f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f

In this example, the nodes are implicitly ordered:

0. AD:4349445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f
1. HID:4849445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f
2. SID:534944305f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f

The numbers following each XID indicate to which other nodes a node has outgoing edges (in order of priority). The 2 and 0 in the first line are the implicit starting node's outgoing edges. The service ID is the sink node and thus has no outgoing edges (and is not followed by a '-').

TODO: show picture

IMPORTANT: Nodes may be listed in any order, with the exception of the sink node which must be listed last.

DAG Manipulation Library

Building DAG strings as described above can be tedious, so the XIA distribution includes a user level library for building and manipulating DAGs. See the documentation.

Annotated Examples

• Python Example
• C Example

Previous: Running Sample Applications

Next: Debugging