Linux Build Procedure for OF-DPA Software

This section details the build procedure for the OF-DPA software using the following environment:

The build machine uses either Red Hat® Linux® 5 and 6.2, or CentOS 5 and 6.2 (64-bit only) as the development environment. CentOS 6.2 is recommended if you will also be using this build machine for building RPMs.
The build machine uses Broadcom Linux or XLP® SDK 2.2.7/3.2 as the cross-compiler and target environment.

Note: It should be possible to use other distributions for the development environment and other development kits for cross-compilation and target files. This file documents compiling for a iProc ARM® (ARMv7) reference platform target.

To successfully build OF-DPA software for a Linux environment, execute the following steps in the order specified.

Build or install the necessary toolchain (see Installing the Broadcom Linux Toolchain).
Extract the open source code (see Extracting the Open Source Code).
Build mkimage (see Building mkimage/mkimage64).
Install and build the Linux kernel (see Installing and Building the Linux Kernel).
Build the OF-DPA code (see Building OF-DPA Source Code).

Installing the Broadcom Linux Toolchain

This section provides information about how to install the Broadcom Linux toolchains for OF-DPA 2.0. The following table contains information about the toolchains provided for the supported architectures and CPUs:

Provided Toolchains
Directory	Architecture	CPU	OS Version
e500v2	PowerPC	E500v2	BRL 3.8
iproc	ARM CPU	ARMv7	BRL 3.6
x86_64	Intel x86	Intel Atom	Ubuntu 12.04

The toolchains are built to run under Red Hat Enterprise Linux 5 (RHEL5), RHEL6, CentOS 5, and CentOS 6, 64-bit. If there is a need for toolchains to run in a different environment, contact Broadcom for assistance.

Note: For OF-DPA x86 with Ubuntu, the Ubuntu 12.04 native toolchain should be used. The cross-toolchains provided are only applicable to PowerPC and ARM CPU based platforms.

To install the toolchains:

Log on to the Customer Support Portal (CSP) and acquire the toolchain file OFDPA_R200_toolchain.tar.bz2.
Log in to the development system as root.
Change to the root directory:
cd /
Uncompress the toolchain file:
tar -xjf OFDPA_R200_toolchain.tar.bz2

The toolchains will be installed to /projects/nwsoft-toolchains/brl/brl_x.x/brl_x.x.x. where x.x/x.x.x is the brl version.
For PowerPC e500v2 CPU-based switches, use the toolchain path:
/projects/nwsoft-toolchains/brl/brl_3.8/e500v2

For ARMv7 CPU-based switches, use the toolchain path:
/projects/nwsoft-toolchains/brl/brl_3.6a/iproc

Note: The toolchains were built specifying Linux headers for version 3.8.13 (for e500v2) or version 3.6.5 (for BRL 3.6) which may not be compatible with building other projects.

Extracting the Open Source Code

After building the toolchain, the operator must extract the open source code. A sample set of commands for extracting the open source code is as follows.

Extracting the Open Source Code Sample Command Sequence

[builduser]$ ls
OFDPA_R200_open_source_support_code.tar.bz2
[builduser]$ tar xfj OFDPA_R200_open_source_support_code.tar.bz2

The various open source packages are unpacked into the OFDPA_R200_open_source_support_code directory.

Building mkimage/mkimage64

Refer to the following command sequence as a guide for building mkimage:

wget ftp://ftp.denx.de/pub/u-boot/u-boot-2012.10.tar.bz2
bunzip2 u-boot-2012.10.tar.bz2
tar xf u-boot-2012.10.tar
cd u-boot-2012.10
make tools
cp tools/mkimage tools/mkimage64

When this process is complete, the mkimage and mkimage64 binaries are available in tools/mkimage and tools/mkimage64, respectively, and should be copied to a location that is accessible via the PATH variable, so that is visible to the OF-DPA build process. mkimage64 is identical to mkimage.

Installing and Building the Linux Kernel

The operator should now be ready to install and build the Linux kernel. The kernel is automatically built as part of the OF-DPA image construction, so there is no need to do a separate build of the kernel.

The Linux kernel provided with the OF-DPA distribution compiles as simply as any other distribution of Linux. The exception is the image packaging. The OF-DPA code image needs to be packaged using the mkimage tool from the u‑boot distribution.

Note: Customers can use their own Linux kernels. It is not necessary to use the provided source. In that case, have the compiled kernel source available so that OF-DPA can build kernel modules against it. See Porting the Linux Kernel for kernel changes necessary to integrate with OF-DPA.

Linux Kernel Install/Build Sample Command Sequence

Refer to the following command sequence as a guide for installing and building the Linux kernel:

iProc ARM Example

The iProc ARM kernel sources are bundled in the open source tarball and also within the OF-DPA source code directory structure. For iProc ARM, the kernel is automatically built as part of the OF-DPA image construction, so there is no need to do a separate build of the kernel. The following information documents the location of the iProc ARM sources within the tree.

The kernel that gets built for iProc ARM BSP can be found in the OF-DPA tree at this location:

..../build_kernels/<40-character-hex-string>/<cpu>

For example, the iproc_hr2 kernel sources are found in this tree:

.../build_kernels/85c52398c1fcca5d9defcffc00679afe33010d31/iproc_hr2

The 40-character string is the SHA ID that corresponds to the version of the kernel that we have provided for that BSP. A BSP that uses this kernel auto-build feature has two places where this SHA ID can be configured:

.../systems/cpu/<bsp>/<kernel version>/kernel.cfg

where:

<bsp> is the name of the BSP
<kernel version> is the generic name for the kernel

Within that file, the BSP may optionally define the Makefile variable GIT_COMMIT_ID to exactly match the 40-character string. If GIT_COMMIT_ID is not found there, the Makefile system falls back to this file:

.../systems/common/<kernel version>/kernel.cfg

For OF-DPA 2.0, the BSPs use only the common version of the kernel.cfg file. In that file, there is this line:

.../bsp/common/brl_3.6/kernel.cfg:export GIT_COMMIT_ID=85c52398c1fcca5d9defcffc00679afe33010d31

The user of a BSP can find this commit ID, and use it to locate the proper version of the kernel sources within the build_kernels subdirectory.

Installing gen_init_cpio: After the kernel has been built, you must copy the usr/gen_init_cpio binary that is generated to a location that is on your path.

If you forget to install this file and perform a make with OF-DPA, then you must do a make clean for OF-DPA after installing gen_init_cpio.

Building OF-DPA Source Code

Users can build OF-DPA as an interprocess mode application or choose to generate the archives necessary to statically link with their code. The sections below provide the build instructions for these modes. In either mode, the SDK is also built as part of the OF-DPA make process. OF-DPA builds the SDK using the SDK Make system.

Build Variables

These make variables control building OF-DPA. They are typically set in the Makefile in the platform output directory. The common variables are:

OFDPA_BASE - top level directory of the OFDPA code.
OUTPATH - directory where the generated output is placed.
L7_TARGETOS_VARIANT - Identifies the OS version used to build with OF-DPA. Used as subdirectory names below the systems directory.
L7_CPU - - Identifies the CPU type used to build with OF-DPA. Used as subdirectory names below the systems directory.
CROSS_COMPILE - base name of the cross compiler tools.
KERNEL_SRC - the location of the Linux kernel source code.
PLATFORM_CODE - directory where the platform specific code resides.
kernel_version - Used with either L7_CPU or L7_SDK_PLATFORM to determine the platform name used by the SDK.
L7_SDK_PLATFORM - only needs to be defined if the SDK platform is different than the L7_CPU.

The following make variables are only needed by the iProc systems to address some make issues in the SDK.

TOOLCHAIN_BASE_DIR
BUILDROOT
GCC_LIB_VER
TARGET_ARCHITECTURE

The following make variables are only needed by the Ubuntu switches:

OFDPA_PLATFORM - Used for generating the .deb package name
CREATE_DEBIAN_PACKAGE - If defined, causes a .deb package to be created
DEBIAN_DEPENDS - The list of package dependencies

Interprocess Mode Application

Change to the platform subdirectory (e.g. bin/ly2-trident-fsl14 ) and type "make". This will generate the following binaries in the directory specified by DELIVERABLES_DIR. The default setting for DELIVERABLES_DIR is output/<platform>/build/ as defined in Make.common.

ofdpa: the OF-DPA executable. Clients invoke APIs via Remote Procedure Calls (RPCs). The OF-DPA process is started using the command "./ofdpa &" from the switch Linux prompt.
ofdpa.dbg: the OF-DPA executable with debug symbols. This is used with the GDB debugger.
librpc_client.so.1: the shared library used to dynamically link to invoke the OF-DPA APIs via RPC.
linux-kernel-bde.ko/linux-user-bde.ko: kernel objects used by the SDK.

Single Process Mode Application

Users can choose to link OF-DPA statically with their application. The OF-DPA build target 'libraries' generates the archives for OF-DPA code. By default, the SDK code archives are also generated on invocation of 'libraries' target. The archives are generated in LIBRARIES_DIR directory. Statically link the OF-DPA archives with the user application code to generate the executable image.

The OF-Agent application is an example of a single process mode application. This application is built by the make target 'ofagentapp'. It statically links an example port of the Indigo agent with OF-DPA. The OF-DPA process is started using the command "./ofagentapp &" from the switch Linux prompt.

Note: The RPC interface used in the Interprocess Mode Application is also available in the Single Process Mode Application.

Client and User Application Guidelines

Applications accessing the OF-DPA APIs must invoke ofdpaClientInitialize() before invoking any other OF-DPA APIs.

Clean Targets

Use the following commands to clean the builds

make clean: deletes the contents of all the subdirectories of output/<platform> except sdk
make clean-all: deletes the contents of all the subdirectories of output/<platform> including sdk

OFDPA Documentation

Use the following command to generate OF-DPA documentation

make ofdoc

Building OF-DPA Example Applications

Some small example applications are provided along with OF-DPA that invoke OF-DPA APIs. These applications typically dump tables or perform trivial tasks. They can be examined as a model for writing code to access the OF-DPA API. These applications access OF-DPA via the RPC interface.

Building the Example Programs

The example applications may be built using following command.

#make client

This command must be issued in the directory ofdpa/output/<platform>.

This command also creates the Python interface to the RPC shared library.

Building OF-DPA for Ubuntu-based switches

For Ubuntu-based switches, a .deb package will be built if the make target is package.

#make package

This package can be installed using the usual package managers. OF-DPA will be installed as upstart services. There are two services: ofdpa and ofagentapp. The ofdpa service starts ofdpa in Interprocess mode. The ofagentapp service starts OF-DPA in Single Process mode with the Indigo OpenFlow agent.

Example: To start the ofdpa service:

#start ofdpa

To stop the ofdpa service:

#stop ofdpa