: Los actores principales (Stakeholders) ysus perspectivas

Porting OpenRG to a Different Architecture

OpenRG can be ported to various hardware platforms. The porting process might require changes to OpenRG's distribution, platform definition and initialization, boot sequence, memory configuration and I/O configuration.

The following section describes the OpenRG porting procedure, which is relevant for all platforms. Still, every platform has its own unique characteristics and may require different modifications. The rest of this chapter provides you with general porting tips, and with instructions for porting OpenRG to Intel's IXP425-based reference design platforms. These platforms include the IXDP425 (also known as Richfield) and the Coyote platforms.

7.1 Porting Guidelines

Porting OpenRG to a certain architecture is basically a merge between the OpenRG codebase and a Board Support Package (BSP) provided by the vendor. A BSP consists of Linux kernel and drivers, which the vendor has adapted for a specific hardware platform. The source code of such Linux contains a number of changes made to meet the requirements of the platform's various devices. To review these code changes, you must also obtain a standard Linux codebase of the same version as the supplied BSP. Note that successful porting largely depends on your careful review of the BSP's drivers and kernel APIs.

7.1.1 Porting Prerequisites

To start porting OpenRG to a BSP, you will need the following:

Hardware

A hardware debugger and scripts (if available) Boards with Linux already burnt to the Flash A removable Flash (if available)

A JTag interface – a special socket on the board used for connecting a debugging device.

Software

• A platform-specific toolchain

• A user mode burning utility

• The following source code:

A full Linux 2.4/2.6 BSP

Clean Linux codebase of the same version as the BSP (for Diff generation) A compilable bootloader, including bootstrap code

• BSP drivers for external peripherals (such as Flash, Serial, Ethernet, ADSL, DSP, etc.) BSP Documentation

Board schematics Hardware specification Programmer's guide

In addition, verify that the BSP code compiles properly. After compiling the BSP image, burn it to the board's Flash using a hardware debugger or a bootloader. When Linux is up and running, perform sanity checks of network and serial connections, DSP, etc.

7.1.2 Reviewing Code Differences

After verifying that the BSP you received is errorless, use a diff command to analyze the code differences between the clean Linux codebase and the BSP. You should check the

contents of the BSP's new directories, as well as examine modified or new drivers. In addition, any modifications in the generic kernel code must be carefully reviewed and their purpose understood.

Ideally, all the BSP source code modifications must be concentrated in the following new directories:

• ARM architecture:

arch/arm/mach-<...>

include/asm-arm/arch-<...>

• MIPS architecture:

arch/mips/<...>

include/asm-mips/mach-<...>

• New driver directories

However, changes may also exist in such directories as arch/<...>, include/asm-<...>, net, kernel, fs, drivers, include/linux, include/net.

As the next step, examine the usage of default and new configuration flags, in order to properly map various parts of the BSP and OpenRG code. Note that a Linux 2.6-based BSP contains the Kconfig textual file, which explains the purpose of each configuration flag. In case you do not understand some part of the BSP code, you may look for it in a higher Linux version, or in other architectures—it is possible that this code has been merged to the BSP from there.

7.1.3 Merging the BSP into OpenRG

After the code changes have been reviewed, start organizing the new directory structure according to the following guidelines:

Platform-specific code (arch-<...>) for CPU support and SoC drivers (such as ETH, DSL, UART, GPIO), and the include directory should be placed under the vendor/<bsp_name>/

kernel directory.

All generic external device drivers from other vendors (wireless, switch, DSP, etc.) should be placed under the vendor/<driver_vendor>/drivers directory.

Import all new directories for future use, in case you would like to upgrade the distribution.

After preparing the directory structure, examine the BSP's kernel code. Remove as much non-relevant code changes as possible. Ideally, there should be no code modification within the generic kernel code (excluding Makefiles). In addition, try to replace the significant code changes with a generic or Jungo's implementation. If you fail to do so, leave the vendor's code changes intact, and protect them with configuration flags.

In addition, check if you can use the original OpenRG toolchain. This may help you to avoid toolchain bugs, libc compatibility problems (lib-gcc), etc. If you cannot leave the original toolchain intact, integrate the BSP's toolchain into OpenRG (look at the jmk/env_root.mak and jmk/rg_root.mak files as a reference).

7.1.4 Compiling an LSP Image

After merging the BSP code to OpenRG, you should compile a Linux Support Package (LSP) image, containing a minimal amount of modules. To compile the image, perform the following:

1. Determine the cross-compilation flags. To do so, compile the BSP, and look at compilation flags of its kernel and user mode. In addition, examine the arch/<...>/Makefile, as well as look at pkg/build of similar architectures. For more information about specific flags, consult the GCC Documentation.

2. Add the cross-compilation flags to pkg/build/config_host.c

3. Determine the kernel configuration flags, which are based on the BSP's default and auto-generated configuration flags. Use defconfig as a reference. Filter out the irrelevant flags, and leave a minimal set of necessary ones (Arch, ETH, UART). Later, you will be able to add more flags (Flash/MTD, WiFi, USB, etc.).

4. Carefully sort the flags into the following groups: dist_config, hw_config, and feature_config.

5. If necessary, make changes in os/Makefile.vmlinuz.

6. Configure the required modules (Ethernet, Flash) according to the BSP.

7. Configure the load address, and the kernel entry:

ARM

Load address – PAGE_OFFSET (include/asm-arm/arch-<...>/memory.h) Kernel entry – TEXT_OFFSET (arch/arm/Makefile)

MIPS

Load address – LOADADDR (arch/mips/Makefile) Kernel entry – check in the BSP code

8. In case the BSP and OpenRG use incompatible Linux versions, you may try to modify the BSP drivers to fit the kernel APIs of OpenRG. Alternatively, if the code differences are concentrated in one place, modify or upgrade the relevant part of the BSP Linux APIs.

However, if the differences are extensive and scattered throughout the kernel code, you may upgrade OpenRG's Linux.

Note: It is highly recommended that you avoid performing partial or full upgrade of the kernel code.

Finally, compile the LSP image and burn it to the board. Once it is up and running, check functionality of various device drivers.

If the LSP image is functioning properly, create a full distribution according to requirements, add a Flash layout (rg/vendor/<...>/flash_layout) and mtd partitions. Then, compile a full image, run it, and debug if necessary.

7.1.5 Debugging FAQ

Problem: Kernel does not boot.

Possible solutions:

• Verify that UART is properly configured.

• Verify that the load address is correct.

• Verify that the boot-loader uses a correct load address and kernel entry point.

• Use prom_printf or similar (the architecture's setup.c or prom.c).

• Directly write to UART registers.

• Follow the boot sequence (start_kernel).

• Use a hardware debugger.

Problem: Kernel boots, but hangs or crashes after console_init.

Possible solutions:

• Use Objdump as explained in Section 20.4.6.

• Use printk as explained in Section 20.4.1.

• Follow the last console messages.