RidgeRun Old 2011Q2 SDK User Guide
- 1 Read First
- 2 SDK Overview
- 3 Installing the SDK
- 4 SDK Components
- 5 Using the SDK
- 5.1 Root Password Entry
- 5.2 How to configure the SDK
- 5.3 How to compile the SDK
- 5.4 How to compile an arbitrary directory inside the SDK
- 5.5 Other SDK Make targets
- 5.6 How to add my application to the SDK
- 5.7 How to update the SDK with the latest patches from RidgeRun
- 6 Appendixes
There are different versions of the RidgeRun's SDK depending on the target processor you plan to use. The information in this document is general and is completely agnostic of the type of hardware or SDK configuration that the customer is using. For more specific information refer to the specific SDK documentation for your target hardware.
The RidgeRun Linux 2011.Q2 SDK, features:
- Linux Kernel 2.6 (specific kernel depends on the platform).
- ARM GCC based toolchain (specific version depends on the platform).
- Bootloader (specific version depends on the platform).
- Integrated build and configuration system.
- Deploy utilities to automated deployment of firmware during development cycle.
Relevant features of the SDK are:
- Full integration of the whole SDK configuration under one main menu. This allows the access to all the configuration menus for toolchain, bootloader, file-system and others from a centralized point.
- Transparently management of architecture dependencies. In order to made changes as target hardware, toolchain or bootloader configurations, just choose the correct configuration of your in the SDK main menu and all the necessary dependencies will be handled by the SDK.
- Easy integration of new user applications.
Supported Linux Distributions
RidgeRun SDK have been developed and tested on Ubuntu, and requires at minimum Ubuntu 9.04; however is strongly recommended to use the latest stable version of Ubuntu. Other Linux distribution may be used if they provide glibc 2.4 or up, but have non been tested and the SDK host tool checking will need to be bypassed or extented.
Ubuntu is a well supported and easy to use Linux distribution with commercial support. You can get pre-installed and enterprise supported Ubuntu desktops for your company.
The SDK can be used over a virtual machine, but it is not recommended due to performance concerns. RidgeRun SDK is a source code “build from scratch” system, and the build process is I/O intensive. Virtual machines technologies perform better on CPU intensive applications, but not I/O intensive ones, unless you use a optimized hardware configuration. In addition, the SDK installer uses the serial port, which has been known to drop data when used with a VM.
Please contact RidgeRun support for more information or if you require support for other distributions.
Installing the SDK
RidgeRun delivers the SDK in either two ways: a binary installer for x86 platforms, or for customers with a established development relationship through a custom SCM (typically svn) repository. This instructions details the installation procedure for the binary installer. If you are using a shared SCM repository, please contact RidgeRun for detailed instructions.
Listed below are the minimum recommended requirements for installing and using the RidgeRun SDK:
- A host computer with a 686 or better family processor
- 1 GB free hard disk space
- A Linux distribution configured on the host computer. For instructions for setting up on Ubuntu Linux please refers to Appendix I.
- Target hardware for the SDK
- Optional: a network card installed and configured on the host computer
- Optional: Internet connection for SDK updates
The RidgeRun SDK is delivered as binary self installer.
RidgeRun toolchains must be installed on /opt and therefore you need either to install the toolchain as root, or to have write permissions over /opt for your normal user. If you decide to assign your user permissions over /opt:
$ sudo chown $USER /opt
It is recommended to install the SDK as normal user (without using sudo). When installing the SDK as normal user, the default installation target for the SDK is /home/$USER/<name and version of your SDK>.
So, after you get the binary file for the SDK proceed to execute the installer:
If you are running from a graphical UI it will show the graphical installer, where you can follow the instructions to install the SDK. Otherwise it will use the console installation method.
The other option is to install the SDK as superuser. If you decide to install as superuser it is recommended to change the owner ship of the SDK directory to your normal user after the installation, since working as root is not recommended, and the SDK has support for handling root-required operations with sudo. When installing as superuser the default installation target for the SDK is /opt/<name and version of your SDK>.
If you want to change the ownership of your SDK development directory after installing the SDK you can execute:
$ sudo chown $USER -R /opt/DMXXXSDK12345
This SDK has several main components that will be explained in the following sections, they are: bootloader, file-system, kernel and toolchain. There are other non standard components that depends on the specific client configuration, check the specific documentation for such components.
The bootloader allows the loading, storing, and invoking of a Linux kernel and root file system. In normal operation, the bootloader resides in the boot storage device (NOR flash, NAND disks, etc) at the reset vector. It is the first program run on power up and, unless something else is specified, the bootloader will typically transfer control to the stored Linux kernel and file system.
Currently the RidgeRun SDK's support U-Boot bootloader. Information is available at http://sourceforge.net/projects/u-boot and in the SDK directory $DEVDIR/bootloader/u-boot-*/src/doc.
The user interface communicates over the board's serial line with a host terminal session such as minicom on Linux, or TeraTerm on Windows. Do not use HyperTerm since it does not support a 8 bit binary transfer mode. Using HyperTerm will cause the images being downloaded to be corrupted.
The target file system holds the master file system structure used to create the target file system. This includes all the files, drivers, nodes and others entries, that will be mounted in the target board when Linux finishes to boot up.
The Linux kernel supplied with your SDK is pre-configured and ready for use. If your project requires components that are not contained in the default RidgeRun kernel, you may want to change the kernel configuration.
Holds the tools and utilities used to build applications and other code for the target hardware, in other words, supports cross compilation, which is the process of compiling on your host machine executables for a different target processor.
Using the SDK
The SDK is pre-configured so that it can be installed, compiled and tested out from the box. The SDK is pre-configured with a default configuration which may not include all that is needed during future development steps for your target hardware. In the following sections we will describe the necessary steps to modify and re-configure the SDK.
Root Password Entry
During the SDK's installation process and building the target file system, you will be asked for the root password several times. Root privileges are necessary at certain points in the configuration of the target file system image (creation of devices, setting of file ownership, etc.). The build process provides an alternative to reduce the number of times you have to enter passwords. If you define the following environment variable in your shell startup script (e.g. .bashrc):
Then you will be asked for a password only once. For Ubuntu the password that you provide is your personal password, not the root password.
In order for the sudo command to work correctly, you must have an entry for your user ID in /etc/sudoers. You need to edit this file as the root user. Also, you can add a default timestamp entry to disable sudo from periodically asking for your user password. The following two lines can be added to the /etc/sudoers file to reduce the number of times you have to enter passwords.
Defaults: <user ID> timestamp_timeout=-1 <user ID> ALL=(ALL) ALL
More information about sudo can be found at http://www.courtesan.com/sudo/
How to configure the SDK
In the root directory where the SDK is installed run the make target “config”. For example:
$ make config Ridgerun Linux SDK DM320 TI SoC EVM Board configuration Processing toolchain... Processing kernel... Processing fs... Entering arch... Entering mach... Entering apps... Processing bootloader... #
Then a menu like the one in Figure 1 will show up:
From this main menu it is possible to configure SDK components like: architecture specific memory addresses, toolchain path and flags, bootloader specific memory addresses, the kernel configuration, the file system type and the applications that will be added to the target file system.
The help option of every menu is useful to understand the different options of the SDK components. The detailed SDK configuration documentation can be found there.
Once the SDK configuration is finished save it and compile the SDK.
How to compile the SDK
In the SDK each component can be compiled separately or the whole SDK can be compiled in one command. For example to make everything:
$ make Ridgerun Linux SDK DM320 TI SoC EVM Board configuration Processing toolchain... Build complete Processing kernel... CHK include/linux/version.h SPLIT include/linux/autoconf.h -> include/config/* SYMLINK include/asm-arm/arch -> include/asm-arm/arch-dm320 CHK include/linux/compile.h CHK usr/initramfs_list CHK include/linux/compile.h UPD include/linux/compile.h Kernel: arch/arm/boot/Image is ready Kernel: arch/arm/boot/zImage is ready Building modules, stage 2. Build complete Processing fs... Entering arch... Entering base... Entering mach... Entering apps... Entering busybox-1.1.2... Entering dosfstools-2.11... Entering arch/targets... Entering initrd... Entering mach/targets... Build complete Processing bootloader... Building images for bootloader Build complete
or you can compile each component separately:
$ make kernel Processing kernel... CHK include/linux/version.h SPLIT include/linux/autoconf.h -> include/config/* SYMLINK include/asm-arm/arch -> include/asm-arm/arch-dm320 CHK include/linux/compile.h CHK usr/initramfs_list Kernel: arch/arm/boot/Image is ready Kernel: arch/arm/boot/zImage is ready Building modules, stage 2. Build complete $ make fs Processing fs... Entering arch... Entering base... Entering mach... Entering apps... Entering busybox-1.1.2... Entering dosfstools-2.11... Entering arch/targets... Entering initrd... Entering mach/targets... Build complete $ make bootloader Processing bootloader... Building images for bootloader Build complete
There are some options that can be passed to the make command:
- VERBOSE. This option set the verbose level of the build system while building the SDK.
- Level 0: no messages are printed, all command outputs are redirected to LOGFILE (see below).
- Level 1: Commands, info and warning messages will be shown
- Level 2: Same level 1, but using verbose kernel build
$ make VERBOSE=1 Ridgerun Linux SDK DM320 TI SoC EVM Board configuration if [ -d toolchain ] ; then echo -e "\040" "Processing toolchain..."; export PATH="/opt/RidgeRun/dm320/linux-2.6/crossdev"/bin:$PATH ; make -C toolchain DEVDIR=/home/trivas/cdx-devdir -demo TABINDEX="\040\040\040"; fi Processing toolchain... make: Entering directory `/home/trivas/cdx-devdir-demo/toolchain' make -C uclibc build make: Entering directory `/home/trivas/cdx-devdir-demo/toolchain/uclibc' make: Nothing to be done for `build'. make: Leaving directory `/home/trivas/cdx-devdir-demo/toolchain/uclibc' echo -e "\040\040\040" "Build complete" Build complete make: Leaving directory `/home/trivas/cdx-devdir-demo/toolchain'
- LOGFILE. This option is similar to VERBOSE, except that all the log, info and warning messages will be redirected to the file path specified after the LOGFILE parameter. The log file path must be an absolute path and the directory path to such file must exist. The LOGFILE option is only useful at VERBOSE level 0. Example:
$ make LOGFILE=/home/trivas/temp/logfile Ridgerun Linux SDK .... Build complete $ cat /home/trivas/temp/logfile <log file contents>
How to compile an arbitrary directory inside the SDK
The SDK build system uses several system variables that are set-up by the main Makefile in order to build the different components, and find the toolchain components. Therefore if you attempt to compile a single directory inside the SDK structure, it will fail.
A workaround for such limitation is possible and requires two steps:
- Set and export the DEVDIR environment variable to the absolute path of your development directory:
$ export DEVDIR=/path/to/devdir
- Include on your PATH variable the path to the binary cross-compiler toolchain being used:
$ export PATH=/path/to/toolchain/binaries:$PATH
However the SDK offers a simplified method to set the DEVDIR and PATH values:
$ `make env`
After you perform these steps you can go inside any particular directory of the SDK and execute the makefiles contained within them. Be aware that you should recompile the file system images or any other component in order to update your target.
Other SDK Make targets
From within the root of the development directory (devdir)'s root, and through the Makefile file that's been mentioned, many commands and utilities some of which have already been discussed above can be used. The following is a list of these, commented with their respective functionality and usage. Note that at any time a similar guide can be displayed by using the "Make help" command, present within that same file in the devdir's root directory.
- build: Builds the kernel, target File System and Bootloader.
- kernel: Builds kernel.
- fs: Builds the target filesystem.
- cmdline: Builds cmdline for target kernel (fs target does the same as well).
- bootloader: Builds the bootloader.
- config: Enters SDK configuration mode.
- config_batch: Attempts to configure without user interaction.
- clean: Deletes all derived files.
- update: Checks for repository updates for the SDK.
- show_updates: Checks for available updates for the SDK's release; use revision=<number> to specify a log (svn log command) or showdirs=1 to enable showing change details in the log displayed.
- env: Displays commands to run to setup shell environment.
- coreconfig: Select toolchain, bootloader, and kernel (updates bsp/mach/Make.conf)
- doc: Generate the SDK API documentation into the documentation folder.
- prelink: Prelinks the root filesystem.
- install: Installs all out of date images to target.
- installbootloader: Install bootloader to target.
- installmtd: Install uBoot MTD partition table.
- installkernel: Install kernel to target.
- installfs: Install file system to target.
- installcmdline: Install uBoot kernel command line.
- installbootcmd: Install uBoot boot command.
- svnup: recursively run the 'svn up' command.
- VERBOSE: Set to 1 to output executing commands
- LOGFILE: Set to built output filename
Make update parameters
- FORCE_UP: Set to force the application/removal of patches
- DEBUG_UP: Set to output the executing commands
U-boot Installer Parameters ($DEVDIR/installer/u-boot-installer)
- PORT: Host serial port to use for install
- HOST_IP: Host IP address to use for TFTP install
- FORMAT: Set to 1 to force SD card to be formatted
How to add my application to the SDK
This is a quick reference for introduction on how to build applications with the SDK, for more detailed instructions please refer to the “Development and Integration Guide” found in the documents of the SDK.
Under your SDK development directory is a directory named myapps. This directory allows customers to locate their own applications to be run on the target hardware. Inside this directory is a Makefile with logic to detect new applications and add them to the SDK build procedure.
A example hello application can be found on the myapps directory and can be use as reference for creating new customer application.
Step 1: Creating the application directory
Go into myapps directory and create a new directory for your application:
$ cd $DEVDIR/myapps $ mkdir NewApp $ cd NewApp
Step 2: Create the build system files
Create a file named “Config”. This file will contains logic to select if your application should be build within the SDK. A simple example file is:
config USER_APPS_NEWAPP bool “NewApp Customer Application” default y help Build my NewApp program
For further information about the syntax of this file check $DEVDIR/bsp/bspc/kconfig-language.txt
HINT: Look at other Config files in the SDK to find one that is similar to your needs and use it as your starting point.
Once the file is created you can run the “config” target on your system to enable the build of the new application. A screen will appear as follow:
Then create a file named Makefile. This is a standard Makefile file to build your application, however it requires certain rules to be integrated with the SDK build system.
HINT: a template Makefile should look like this:
# # myapps/NewApp/Makefile # .PHONY: build chkconfig preconfig buildfs install clean ifeq ($(DEVDIR),) $(error ====== DEVDIR variable is empty, invoke this Makefile from the SDK root, or provide the path to it =====) endif include $(DEVDIR)/bsp/mach/Make.conf build: <build commands for your app> install: <install commands for your app> clean: <clean command for your app> # Empty but required targets chkconfig: preconfig: buildfs:
The rules for the SDK Makefile are:
- Check the definition of the DEVDIR environment variable
- Include the file $(DEVDIR)/bsp/mach/Make.conf
- Have the following phony targets: build, chkconfig, preconfig, buildfs, install, clean
- The build, install and clean targets should be active only if the application configuration symbol is equal to 'y'
In order to compile the files with the proper cross-compiler you can use the follow environment variables (imported from the Make.conf file):
- CC, CPP, LD, AR, AS, OBJCOPY, OBJDUMP, STRIP, CXX, RANLIB: those variables contains the name of the corresponding application from the toolchain for cross-compiling.
- CFLAGS: contains the flags that must be used when compiling programs in order to work properly with the cross-compiler.
HINT: You can see how to use the variables by looking at the hello example Makefile.
How to update the SDK with the latest patches from RidgeRun
NOTE: If you are a customer using a custom SCM repository shared with RidgeRun, this instructions aren't valid, since updates are delivered directly into the shared SCM.
RidgeRun SDK includes a feature to update your SDK with the latest patches provided by support engineers. This feature requires Internet connectivity.
In order to update your SDK to the latest patches, perform the follow commands:
$ cd $DEVDIR $ make update
You will be asked for an username and password to access RidgeRun support servers. Contact RidgeRun support to get this information.
A brief report of actions will be displayed:
$ make update RidgeRun SDK update tool This program will check against RidgeRun update servers to find and apply updates for your SDK. Please provide the customer user name and password provided by RidgeRun support services in order to access the updates. Username: ridgerun Password: Getting patch list... done RidgeRun SDK update complete, your SDK is up-to date with Patch 002 $
Appendix I: Setting up Ubuntu for use with RidgeRun SDK
Ubuntu Linux is a popular Linux Distribution based on Debian Linux. It's available for different platforms and provides a easy-setup development environment. For more information please visit http://www.ubuntu.com/.
The SDK is developed and tested against Ubuntu. This section describes the required steps to install and setup the required software environment for use of the SDK in Ubuntu, but may be useful if you want to use the SDK in another Linux distribution.
In order to install Ubuntu you need to get a installer CD from the project page. The specific steps to install it can be found on the CD documentation.
Required development packages
Ubuntu default installation is suited for an end-user desktop machine, so it might lack some development packages required to become a workstation. In order to install those packages you require a high-speed internet connection and use of the apt-get program.
The first step consists on upgrading all the current software. Perform the follow steps:
$ sudo apt-get update $ sudo apt-get upgrade
Now you just need to build the SDK; the first step of this process is to check your host system and your workstation packages, you may see something like this:
$ make The system is ubuntu-7.10 running in a 32 bit architecture SYSID: ubuntu-7.10_32 Checking for host packages required by the SDK build system: buildsystem (build-essential) is installed libtool (libtool) is installed make (make) is installed mtd-tools (mtd-tools) is installed ncurses (libncurses5-dev) is installed texinfo (texinfo) is installed tftpd (tftpd) is installed minicom (minicom) is installed Ridgerun Linux SDK DM355 Texas Instruments EVM Board Processing toolchain... Build complete Processing kernel... CHK include/linux/version.h ...
If your host system is not one of the supported systems, the first part of this check will fail and show you a message similar to the following:
ERROR: your host system is not oficially supported by RidgeRun SDK please contact RidgeRun support if you need support for this distribution NOTE: your system may still work for building this SDK, is just not tested
If you are working with a supported system such as Ubuntu the packages verification process will start to check all the needed and recommended packages as follow:
... The system is ubuntu-7.10 running in a 32 bit architecture SYSID: ubuntu-7.10_32 Checking for host packages required by the SDK build system: buildsystem (build-essential) is installed
If there is any kind of problem during the verification process, the next part of the process will tell you which packages are missing, and also will alert you if the missing package is vital for building up the SDK, or if it is a highly recommended package. For example an error will look something like this:
The system is ubuntu-7.10 running in a 32 bit architecture SYSID: ubuntu-7.10_32 Checking for host packages required by the SDK build system: >> buildsystem (build-essential) is NOT installed ... There are missing packages, please install them: build-essential make: *** [.oscheck] Error 1
To install the missing packages use the the apt-get program (for more information about apt-get do: man apt-get). For example:
sudo apt-get install build-essential
If there is some kind of warnings you will be alerted and you could chose to stop your building process in order to correct the warning or continue the installation. NOTE: if there is only warnings the message will be displayed just one time, the next time you won't be notified.