dagconfigapi(3)

NAME
DAG Configuration and Status API - configure and read status from Endace DAG cards

SYNOPSIS
#include "dag_config.h "
#include "dag_component.h "
#include "dag_attribute_codes.h "
#include "dag_component_codes.h "

DESCRIPTION

Introduction

The DAG Configuration and Status API allows software developers to programmatically configure Endace DAG cards. Currently the following DAG cards are supported:

    *   DAG 3.7D (dual DS3/E3).

    *   DAG 3.7G (dual Gigabit Ethernet with optional failsafe relays).

    *   DAG 3.7T (16 E1/T1 with onboard XScale processor).

    *   DAG 3.8S (dual OC-3/OC-12 with pluggable optics).

    *   DAG 4.3GE (dual Gigabit Ethernet with pluggable optics/copper).

    *   DAG 4.3S (single OC-48).

    *   DAG 4.5G2/G4 (dual/quad Gigabit Ethernet).

    *   DAG 5.0SG2 (dual Gigabit Ethernet or OC-3/OC-12/OC-48).

    *   DAG 5.0SG2A (dual Gigabit Ethernet or OC-3/OC-12/OC-48 with built-in co-processor).

    *   DAG 5.2X (single 10 Gigabit Ethernet).

    *   DAG 5.2SXA (single 10 Gigabit Ethernet or 0C-192 with built-in co-processor).

    *   DAG 5.4GA (dual Gigabit Ethernet with built-in co-processor).

    *   DAG 5.4S12 (dual OC-3/OC-12 or Raw OC-3/OC-12).

    *   DAG 5.4SA12 (dual OC-3/OC-12 or Raw OC-3/OC-12 with built-in co-processor).

    *   DAG 5.4SG48 (dual Gigabit Ethernet, OC-3/OC-12/OC-48 or Raw OC-3/OC-12/OC-48).

    *   DAG 5.4SGA48 (dual Gigabit Ethernet, OC-3/OC-12/OC-48 or Raw OC-3/OC-12/OC-48 with built-in co-processor).

    *   DAG 7.1S (quad OC-3/OC-12).

    *   DAG 7.5G2/G4 (dual/quad Gigabit Ethernet).

    *   DAG 8.1X (single 10 Gigabit Ethernet).

    *   DAG 8.1SX (single 10 Gigabit Ethernet, OC-192 or Raw/WAN OC-192).

    *   DAG 8.2X (single 10 Gigabit Ethernet with transmit).

    *   DAG 8.4I (dual SDRx4 Infiniband).

    *   DAG 8.5IF (dual SDRx4/DDRx4 Infiniband).

Endace DAG cards allow captured packets to be transferred to host PC memory at full line-rate, with zero packet loss guaranteed even in worst-case conditions.

Rationale

The Configuration and Status API is intended to add functionality to the Endace DAG card API that has previously been exposed through the command line utilities dagthree(1), dagfour(1), dagsix(1), dagrom(1), and dagld(1). This allows third-party software developers to perform the following tasks from within their own application software:

    1   Resetting a DAG card.

    2   Loading firmware images onto a DAG card.

    3   Setting and retrieving the hardware configuration.

    4   Retrieving status and statistics information.

The mental model of a DAG card implied by the Configuration and Status API is a hierarchical tree of components, with each component having a set of attributes. Some of these attributes provide status information and are read-only, while others configure properties of the card and are read-write.

    Root Component
      |
      +--- Component A
      |      |
      |      +--- Attribute A-1
      |      +--- Attribute A-2
      |      +--- Attribute A-3
      |      +--- Attribute A-4
      |
      +--- Component B
      |      |
      |      +--- Attribute B-1
      |      +--- Attribute B-2
      |      |
      |      +--- Component B1
      |      |      |
      |      |      +--- Attribute B1-1
      |      |      +--- Attribute B1-2
      |      |
      |      +--- Component B2
      |             |
      |             +--- Attribute B2-1
      |             +--- Attribute B2-2
      |
      +--- Component C
             |
             +--- Attribute C-1
             +--- Attribute C-2
             +--- Attribute C-3

Changing the configuration of a card requires getting a reference to the card, then a reference to the desired component, and finally a reference to the desired attribute of that component. The attribute reference can be used to retrieve (and possibly modify) the attribute value. For example, in order to see whether a port is active one needs to get a reference to the card, then a reference to the port component, and finally a reference to the 'active' attribute of the port component. Reading the attribute value provides information about the status of the port, and writing a value to the attribute configures the status of the port. A sample program that displays the 'active' attribute for all parts on a DAG card appears below.

There are two different types of attributes present on DAG cards. Configuration attributes represent properties of the card that can be modified, and include such items as:

    *   PoS or ATM mode for SONET cards.

    *   Auto-negotiation mode on/off for Ethernet cards.

    *   Variable or fixed-length packet capture.

    *   Snap length for packet capture.

    *   Amount of memory allocated to each receive and transmit stream.

Status attributes represent properties of the card that are read-only, and include such items as:

    *   Physical layer error indicators.

    *   PCI bus speed.

    *   Number of frames that failed the Frame Checksum.

    *   The number of receive and transmit streams supported by the firmware.

The precise set of attributes and components presented by the API depends on the specific DAG card model and the capabilities of the loaded firmware image(s).

Components

The Configuration and Status API models a DAG card as a set of components with each component containing a set of attributes that allows the component behaviour to be changed. Some components are common across all DAG cards:

    Root Component
        The root component is a special component that has no attributes, but forms the root of the tree of components. All other components are descendents of the root component.

    Generic Packet Processor Component
        The Generic Packet Processor (GPP) creates an ERF record from each captured packet (see erf(5) for more information about this format). Its snaplen attribute can be configured so that it captures a fixed number of bytes from each packet seen on the network.

    PCI Burst Manager Component
        The PCI Burst Manager handles the transfer of the captured packets to receive stream memory buffers, and from transmit stream memory buffers back to the card for transmission. This component can be used to check the size of the memory buffer allocated, and to count the number of transmit and receive streams present. On some DAG cards the 'overlap' attribute is present and can be set to enable inline packet forwarding between two interfaces.

    Stream Component
        Stream components model receive and transmit streams. The number of stream components present will depend on the loaded firmware image(s). Stream components can be used to allocate memory to receive or transmit streams.

    Port Component
        A port component is used to configure and read attributes specific to the line interface. The specific attributes present will depend on the specific DAG card model, but there are similarities between cards designed for the same network protocol, e.g. Ethernet cards have similar attributes associated with their port components. In contrast the port component of a SONET card will not share many attributes with an Ethernet card's port component.

Attributes

Each component may possess a number of attributes. Reading an attribute's value provides information about the state of a DAG card, and writing to an attribute affects the behaviour the DAG card. The attributes themselves are divided into two different types, those used to represent status and statistics information and those used to represent configuration information. The dag_config_get_attribute_config_status(3) function is used to check if an attribute is marked as a status or configuration attribute. Status attributes are read only attributes, and writing to them has no effect. The API provides functions to deal with attributes depending on whether they are configuration or status specific.

Sample Application

The following application illustrates how the API is used. It queries the 'active' attributes of all ports on the card and displays the result. Error-handling code has been omitted for clarity.

#include "dag_component.h"
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, const char* argv[])
{
	dag_card_ref_t card_ref = NULL;
	dag_component_t root_component = NULL;
	uint32_t count; uint32_t i;
	/* Get a reference to the card. */
	card_ref = dag_config_init("/dev/dag0");
	/* Get a reference to the root component. */
	root_component = dag_config_get_root_component(card_ref);
	/* Find out how many ports the card has. */
	count = dag_component_get_subcomponent_count_of_type(root_component, kComponentPort);
	for (i = 0; i < count; i++)
	{
		dag_component_t port = NULL;
		attr_uuid_t active_uuid = 0;
		uint8_t val = 0;
		/* Get a reference to the port. */
		port = dag_component_get_subcomponent(root_component, kComponentPort, i);
		/* Get a reference to the active attribute of the port. */
		active_uuid = dag_component_get_config_attribute_uuid(port, kBooleanAttributeActive);
		/* Read and display the value of the attribute. */
		val = (uint8_t) dag_config_get_boolean_attribute(card_ref, active_uuid);
		printf("Port %u active = %u, i, val);
	}
	/* Dispose of the card. */
	dag_config_dispose(card_ref);
	return EXIT_SUCCESS;
}

FILES
dag_config.h, dag_component.h, dag_attribute_codes.h, dag_component_codes.h.

SEE ALSO
dagapi(3), dagfour(1), dagld(1), dagrom(1), dagsix(1), dagthree(1), erf(5).

BUGS
Report bugs to <support@endace.com>.

LAST UPDATED
$Author: dlim $
$Revision: 10560 $
$Date: 2009-01-29 13:07:44 +1300 (Thu, 29 Jan 2009) $

COPYRIGHT
(c) 2004-2005 Endace Technology, Hamilton, New Zealand. All Rights Reserved.