Building the Cafe SDK

Overview

The Cafe SDK includes source code for demo programs and selected libraries. Developers are free to modify and build the included source code.

The Cafe SDK is designed around a hierarchical makefile-based system. The directory structure is described in the table below.

Path under ($CAFE_ROOT) Description
system/src/build/ Rules and definitions for the build system.
system/src/demo/ Example programs that illustrate various aspects of the Cafe platform.
system/src/lib/ Source code for selected libraries.
system/src/tool/ Tools to build and use various aspects of Cafe.

Note that $CAFE_ROOT is a Cygwin shell environment variable that contains the installation path of the Cafe SDK.

Building

The build system is hierarchical. This means you can navigate to any directory that has a makefile and build all components below that directory.

To build the entire SDK, navigate to the source directory and use make:

$ cd $CAFE_ROOT/system/src
$ make

Alternatively, to build all libraries:

$ cd $CAFE_ROOT/system/src/lib
$ make

To build a specific library - for example, the matrix vector library:

$ cd $CAFE_ROOT/system/src/lib/mtx
$ make

Build Targets

Currently, the Cafe SDK build system supports two build targets: DEBUG and NDEBUG.

The DEBUG target enables error-checking mechanisms such as ASSERT. Debugger symbolics are also generated for the DEBUG target.

The NDEBUG target disables error-checking mechanisms such as ASSERT. The NDEBUG target does not generate debugger symbols, and is suitable for release.

Note that compiler optimizations are enabled for both DEBUG and NDEBUG targets.

Also note that prebuilt SDK libraries are stripped of debugging symbols, for both DEBUG and NDEBUG builds.

The DEBUG target is enabled by default. To generate an NDEBUG build:

$make NDEBUG=TRUE

Build Products

The Cafe SDK uses proprietary binary formats for its executables.

Build Process

To generate RPX and RPL binaries, the build system introduces new processing steps before and after linking. Export/Import information is generated before linking by the preprpl[32|64] tool. After linking, RPLs and RPXs are created by the makerpl[32|64] tool.

Note that the linker generates an intermediate ELF file. The makerpl[32|64] tool uses the ELF file to create an RPX or RPL file. The debugger also references the ELF file.

Note that ELF files are no longer loaded and executed by Cafe.

The Cafe SDK provides the tools in 32-bit and 64-bit variants:

and

The tools provide detailed help at the command line; invoke them without arguments from within the Cafe Cygwin shell:

$ makerpl64

For more information on creating and using RPX and RPL files, see the RPX/RPL Developer Overview document under the Courseware section of the Operating System MAN pages.

Application and System Structure

Your application is comprised of a main RPX program and RPL code modules. Drivers for graphics, audio, and other devices are provided within the Cafe SDK as system RPLs.

For more information regarding the coreinit and coredyn OS modules, see the Customize Memory Management document under the Courseware section of the Operating System MAN pages.

The Small Data Area Optimization (SDA)

The build system supports the linker's SDA optimization to improve runtime performance. Note that:

For information on the command line options and environment variables for controlling this feature, see the Building with Examplemake document.

For information on the linker feature, see the "Special Data Area Optimizations" section of "manuals\build_ppc.pdf", located within your Green Hills MULTI installation directory.

Note that SDAs are disabled by default in the build system. This is because the -auto_sda feature may cause longer link times or out-of-memory link errors for medium and large RPXs.

Experimenting with SDA

For small RPXs, the -auto_sda option is safe.

For larger RPXs, try using -sda=8. If this yields a linker overflow error, try smaller powers-of-two values (4, 2, 1, 0) until linking succeeds.

If -sda=8 works, you can pack more data by increasing the number (9, 10, etc) until linking fails and then using the last successful value.

Alternatively, you can use -sda=none and explicitly designate SDA data by using linker pragmas.

Note that the SDA optimization feature may not work for large RPXs. This is a known issue of the tool chain.

Build Performance - Parallel Make

The Cafe SDK exploits multicore CPUs and the parallel execution capabilities of make to reduce build times. The Cafe SDK decomposes builds into jobs and distributes them to the available cores, which execute the jobs in parallel.

By default, up to four jobs are spawned per logical core. For example, a quad-core CPU with hyperthreading may receive up to 32 jobs from the SDK's build system.

To change the maximum number of jobs per core:

$ make CAFE_MAKE_JOBS=n

Where n is the maximum number of jobs per core.

Alternatively:

$ export CAFE_MAKE_JOBS=n

Note that this change applies only to the lifetime and scope of the current Cafe Cygwin shell.

For a host PC of modest processing power, the parallel build can overwhelm the system. In such a scenario, users may encounter an "Error 126" while building. Serializing the build process can help by setting CAFE_MAKE_JOBS to 1. Alternatively:

$ make default

Serializing the build is also useful when debugging a makefile, as it will prevent the outputs of multiple jobs from interleaving onto the console.

Command Line Help

For more information about running make, help is available at the command line:

$ make help

Building Applications

Integrating an external application with the SDK can be daunting. A simplified makefile and demo program are provided by the Cafe SDK. For more information, see the Building with Examplemake manual page.

See Also

RPX/RPL Developer Overview

Revision History

2013/05/08 Automated cleanup pass.
2012/07/23 Added direct link to Build Products section.
2011/10/19 Examplemake addition.
2011/02/21 Initial version.


CONFIDENTIAL