18-544 Network Design and Evaluation
Programming Help

 

Fall 2005


1 Microengine and XScale programming

This is documentation that you will find useful when programming and using the IXP 2400. Note that most of these documents are intended to be used as reference material. We will provide several copies of these documents in the lab for your use. A more limited set of documents that are useful to read can be found on the main page of the course in the last column of the table with the lectures.

1.1 IXP 2400 Architecture

A good overall description of the IXP2400 architecture can be found in Chapter 2 of the Intel®  IXP2400 Network Processor Hardware Reference Manual (pages 27-48). Chapter 4 (pages 155-180) gives a more detailed description of microengine architecture.

1.2 Microengine Programming

The Intel®  IXP2400/IXP2800 Network Processors Programmer's Reference Manual is a great source of information on programming the microengines. Particularly useful at first will be Chapters 2 and 3 (pages 23-220). For an introduction to Intel coding conventions, consult the Microengine Version 2 (MEv2) Assembly Language Coding Standards document.

All microengine code will be developed in the Workbench, described in detail in the Intel®  IXP2400/IXP2800 Network Processors Development Tools User's Guide Chapter 2 (pages 19-171).

1.3 Application Development and the IXA Framework

The documentation provided on the ``Intel IXA SDK 3.5 Software Framework'' CD is a great source of information on developing applications for IXP network processors. We reproduce parts of the collection here for your convenience.

When looking through the Intel®  Internet Exchange Architecture Software Building Blocks Applications Design Guide, pay particular attention to Section 14, ``Quad Gigabit Ethernet Forwarding Application for IXDP24X1.'' The ipv4_enp2611 project we will be using in this course is based on that application and resembles it very closely. The only differences in the organization of data plane code are

  • The ``Ethernet Transmit'' pipeline stage runs on microengine 1:1 only, leaving microengine 1:2 unused.
  • The ``Packet Rx'' and ``Packet Tx'' microblocks contain a number of bug fixes and other modifications from RadiSys specific to the ENP-2611 board.

Note that Section 14.2.3 does not apply to our setup and should be skipped.

1.4 APIs for Building Core Components, Memory Allocation and Useful Macros

The new portability framework provided by the IXA architecture defines APIs which can be used while programming core components and allocating memory. The following document lists out all the useful APIs for programming.

Allocating memory and patching symbols

As simple sequence of how to alocate memory and use it across core and microblocks, check out the following piece of code:

// Allocate memory for the control block that will be shared

// between the core component and the microblocks

err = ix_rm_mem_alloc(IX_MEMORY_TYPE_SRAM, channel,

sizeof(ethernet_control_block), (void**)đ_context->control_block);

if (err != IX_SUCCESS)

//error handling code

ix_ossl_memset (eth_context->control_block, 0, sizeof(*(eth_context->control_block)));

//Get physical offset of the control block so that

// we can give it to the microblock

err = ix_rm_get_phys_offset( eth_context->control_block, NULL, NULL, NULL, &control_block_phys);

if (err != IX_SUCCESS)

// error handling

// Now patch the control block symbol for all

// of the microengines on which Ethernet Microblocks will run

for (i = 0; i < sizeof(me_numbers); i++) {

ix_imported_symbol symbol;

symbol.m_value = (ix_uint32) control_block_phys;

symbol.m_name = ETHERNET_SYMBOL_NAME;

err = ix_rm_ueng_patch_symbols(i, 1, &symbol);

if (err != IX_SUCCESS)

//error handling

}

For more code reference you could check the following files

  • proj_544fall04/ipv4_enp2611/wbench_project/xscale_init/quad_gbeth_2401/init.c for handling packet data and messages
  • proj_544fall04/ipv4_enp2611/wbench_project/quad_gbeth_memory.h for memory initializations and load time constants

1.5 Frequently Faced Problems

1. Getting root access - Use sudo bash

Everyone has been granted sudo access to the linux machines. In order to copy files as root or run some script, key in the following command

% sudo bash

Without asking for any sort of authentication , this should take you to the root bash where you can copy files or modify files which otherwise would not have been possible.

2. The ENP board refuses to boot even after running host_startup.sh script

The possible reason here is that the fiber adapter on the machine hosting the ENP board has not been recognized. For this, execute the endsys_startup_1.sh script present under /opt/ixp_scripts and then execute the host_startup.sh script. The board should be able to boot now.

1.6 Useful References for Assignment 2

1. The Programmer's Reference Manual

(Chapter on Address Maps (4))

2. The Intel IXA Portability Framework Developer's Manual

(Chapter on Microblocks (4) and chapters on Core Components (8 & 10) )

3. The Intel IXA Portability Framework Reference Manual

(Chapter on Resource Manager (3) and chapters on Core Components (4, 7 & 9 which is on metadata configuration) )

4. The Building Blocks Developer's Manual

(Chapter on Microblocks and chapter on Core Components )

5. The Building Blocks Reference Manual

(Chapter on Core Components. It gives some code examples )

All of these documents are available in the IXA SDK 3.5->Documentation->Tools on the windows machine. You can find the code that you have to modify in the /opt/prof_544_fall04/ipv4_enp2611 folder on the host machine.


2 Running ipv4_enp2611 on Hardware

2.1 Building

2.1.1 Core Component Infrastructure

Note: Make sure that /opt/hardhat/previewkit/arm/xscale_be/bin is in your PATH.

  1. On the Linux host, cd to the directory 
     /opt/ixa_sdk_3.5/src/applications/proj_544fall04/ipv4_enp2611
  1. Issue the command

make -f Makefile.linux_kernel

  1. cd to the directory 
     /opt/hardhat/previewkit/arm/xscale_be/target/opt/proj_544fall04/ipv4_enp2611
  1. Issue the command 
     cp linux_kernel/xscale_be/ixp2400/debug/* .

2.1.2 Microengine Images

  1. Build the ipv4_enp2611 project in the Workbench. Note: make sure the preprocessor symbol USE_IMPORT_VAR is defined, and SIMULATION is not.
  2. Transfer ipv4_enp2611.uof to the directory

/opt/hardhat/previewkit/arm/xscale_be/target/opt/proj_544fall04/ipv4_enp2611 on the Linux host.

2.2 Running

  1. Boot the ENP-2611 board and login as root.
  2. Execute the script init_scripts.sh. (found in /root – your login directory) 
     Note that this script executes the following 3 scripts (found in the directory /opt/proj_544fall04/ipv4_enp2611) in order:
    • make_linux_kernel_devices.sh
    • ipv4_enp2611_run.sh
    • ethernet_rtm_config_linux.sh
  1. On the Linux machine hosting the Radisys ENP-2611 board, execute the script /opt/ixp_scripts/endsys_startup_1.sh
  2. On each Linux machine connected by optical cable to a data port on the ENP-2611, execute the script /opt/ixp_scripts/endsys_startup_2.sh

Note: The last two steps need be performed only once for each end system reboot.

You should now be able to ping across the ENP-2611.

About this document ...

18-544 Network Design and Evaluation
Programming Help

This document was generated using the LaTeX2HTML translator Version 2K.1beta (1.50)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -nonavigation -show_section_numbers -link 2 -split 1 main.tex

The translation was initiated by alex nizhner on 2004-09-08

alex nizhner 2004-09-08