Getting Started with the EMAC OE SDK

TODO: {{#todo: Buggy (03.31.2015-13:42->BS+);(04.08.2015-15:00->BS+);(04.09.15-14:00->MD+);(04.21.2015-10:15->BS+);(04.24.2015-20:00->MD-);(04.28.2015-12:20->MD+) |Brian Serrano|OE 5.0,BS,MD,Buggy}}

The EMAC OE SDK is distributed with a set of example projects intended to demonstrate how to use the EMAC OE toolchain and libraries. This page demonstrates the process of compiling an example project and running it on the target machine. Also, it provides a straightforward guide to the essential steps you need to follow to get started with cross compiling a simple program with gcc and running the program on your embedded machine.

General Information

The EMAC OE SDK is primarily distributed via our apt repository as a deb package for Ubuntu. Using EMAC's apt repository makes installing and updating the EMAC SDK and tools as easy as installing and updating any standard Ubuntu package. This tutorial will show you how to configure your system to use the EMAC apt repository so that you can use the same package management tools you're familiar with in Ubuntu to install and update the EMAC provided SDK and tools.

EMAC also provides a tarball you can extract and install manually in case you're using a distribution other than Ubuntu (or a derivative), but EMAC strongly recommends using an Ubuntu LTS release. The recent Ubuntu LTS releases have been thoroughly tested with the EMAC SDK and tools and are fully supported by EMAC. Given the large number of alternate Linux distributions available, EMAC is only able to provide limited support (in the form of a manually installed tarball) for other Linux distributions.

Each SDK includes the C/C++ header files and libraries compatible with the target hardware. It also includes the C/C++ cross-compiler toolchain components necessary to compile and debug custom application code. The links below will help you get started building and running the example projects on the target hardware.

More information on using Qt Creator with the EMAC SDK is available on the Getting Started With Qt Creator page.

Getting Started with the EMAC OE SDK

Connecting to a Target Board

The next step after establishing a physical connection to the board is logging in. More information on establishing a physical connection to a board is available on the Serial Connections and Network Connections page.

A machine running EMAC OE Linux can be connected to through a serial port or through a network cable. EMAC OE Linux allows users to log in via getty, and SSH (Secure Shell). A getty can be accessed via a serial connection (through a console) while SSH utilizes a network connection. For more information visit the System Log In page.

Setting the Filesystem to Read-Write

The root filesystem on a machine running EMAC OE Linux is mounted read-only by default. In order to put files on the board, you may need to make the filesystem read-write. The Linux Filesystem Organization page has more information regarding which parts of the filesystem are mounted read-only by default versus which parts are always writeable. Note that EMAC recommends installing your program into a read-only portion of the filesystem (according to the guide) to safeguard it from filesystem corruption (such as may be caused by removing power from the board without shutting down the operating system first, which is normal in embedded systems).

To remount the root filesytem in read-write mode, enter the following into the terminal:

root@ipac9x25:~# oemntrw

NOTE

This will only change the root filesystem to read-write for the current boot. When the system is rebooted, the root filesystem will once again be mounted read-only.

Transferring Files

The command line syntax for transferring a file using the SSH protocol is scp file user@host:/directory. SCP or Secure Copy is a way of securely transferring files between a local and remote host. For example, to send the file example.text to the /home directory of a system with the IP address 10.0.6.221, enter the following command:

developer@ldc:~# scp example.text root@10.0.6.221:/home/

Alternatively, you can leave off the path after the colon if you want the file to go directly into the home directory.

developer@ldc:~# scp example.text root@10.0.6.221:

NOTE

This copy operation will fail if the filesystem on the remote machine is mounted read-only, which is the default on most EMAC systems. If you experience this failure, remount the root filesystem read-write (see above) and try again.

Remote Execution

SSH can also be used to execute programs on remote systems without logging in. The syntax for SSH remote execution is ssh user@host "my_command -args file". For example, to run the program hello with the -hi flags on a system with the IP address of 10.0.6.221, enter the following command:

developer@ldc:~# ssh root@10.0.6.221 "/path/to/executable -args"

WARNING!

The description doesn't match the example

Basic Compiling

CMake Compiling

Host Machine Compiling

NOTE

In these examples we are using the Ipac-9x25 board. Your board's processor's architecture will determine which file needs to be sourced. These files come from the EMAC SDK toolchain.

WARNING!

This note belongs in the following section (manual), not here. There should also be a description in the parent section (Compiling) which describes the two subsections, so that the reader will know what's coming and can decide to skip to one or the other, if he/she only wants to learn about one method.

This section demonstrates how to use the EMAC CMake tool to generate CMake files automatically for a project. When using the EMAC SDK there are currently two options for cross compiling:

• arm
• x86

For the purposes of this guide, the arm option will be used for the listed examples.

Navigate to the directory where the project will be located. Then run the CMake new project script.

developer@ldc:~/projects# oe_init_project -n hello.c

If desired, please enter a name for this project, otherwise press Enter to use the default: hello_emac

-- Creating new project directory...
-- Creating new source file...
-- Building custom CMakeLists.txt file...
-- Done.

Do you want to create a build directory for this project? (y/n) y

-- Creating build directory...

Do you want to run cmake for this project? (y/n) y

-- Using system compiler
-- The C compiler identification is GNU 4.8.2
-- The CXX compiler identification is GNU 4.8.2
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Configuring done
-- Generating done
-- Build files have been written to: /home/developer/projects/hello_emac/hello_emac-build

Do you want to compile this project? (y/n) y

Scanning dependencies of target hello_emac
[100%] Building C object CMakeFiles/hello_emac.dir/hello.c.o
Linking C executable hello_emac
[100%] Built target hello_emac

The executable in this case, is now inside the hello_emac/hello_emac-build directory.

Target Machine Compiling

NOTE

There needs to be lead in text here describing what they got from the last section. It's jarring to see that you have to create a directory to cross-compile the project into immediately after you've finished a step which supposedly created an executable for you; it'll make the reader wonder if this is supposed to be steps for them to perform if they didn't perform the one above. So, describe the CMake files that were produced above, what they contain, why they're important, and why they now should create a subdirectory for doing the cross compile. Documentation is supposed to take the mystery out of the process, but if you leave these details out, you're leaving part of it as a mystery. Also, are you sure 'arm' is the only target you should list? What if the reader is on x86? They won't know if they should pass 'Intel', 'i386', 'x86', etc. Tell them by giving them a complete list of options. ;)

Use the following steps to cross-compile the project and send it to a target board. In a terminal, navigate to the base directory of the project (where this document is located).

Create a build directory for cross compiling.

developer@ldc:~/projects/hello_emac# mkdir hello_emac-build-arm

Change directories into the newly created directory.

developer@ldc:~/projects/hello_emac# cd hello_emac-build-arm

Run cmake using the target architecture.

developer@ldc:~/projects/hello_emac/hello_emac-build-arm# cmake .. -DARCH:STRING=arm

Compile the code using make.

developer@ldc:~/projects/hello_emac/hello_emac-build-arm# make

After running the make command, the target executable is now in the hello_emac-build-arm directory. Then copy the executable to the target board. For information on copying the executable file, see the Transferring Files section.

For other ways to generate the CMake files, visit the CMake page.

Manual Compiling

Host Machine Compiling

Create a file called hello.c using a text editor such as vi, vim, nano, or gedit.

WARNING!

Why not just create the file with touch? Why do I need an empty file? What's the point? Oh... it's supposed to have some code in it that you're not telling me about, eh? Uh...

Use the following syntax to compile the program called hello.c:

developer@ldc:~# gcc -o hello hello.c

If there is no error in your code then the compiler will successfully create an executable file called hello in the current directory.

To verify this, enter the following command:

developer@ldc:~# ls -l hello*

-rwxrwxr-x 1 bserrano bserrano 9583 Apr 6 12:45 hello
-rwxr-xr-x 1 bserrano bserrano 129 Apr 6 12:28 hello.c

To run the program, enter the following command:

developer@ldc:~# ./hello

Hello EMAC OE!

OR

developer@ldc:~# /path/to/hello

Hello EMAC OE!

Target Board Compiling

To compile for the target board, you must source the environment-setup-armv5te-emac-linux-gnueabi file.

developer@ldc:~# source /opt/emac/5.0/environment-setup-armv5te-emac-linux-gnueabi

Once you are in the directory with the source file, enter the following command:

developer@ldc:~# $CC -o hello hello.c

NOTE

Once you source the file in your current terminal, you can only use it to cross-compile your program for the target board. You can no longer compile it for your host machine. To compile it to your host machine, simply open a new terminal.

After sourcing the file, copy the program over to the target board using scp. Enter the following command:

developer@ldc:~# scp hello root@10.0.6.221:

root@10.0.6.221's password: hello 100% 9583 9.4KB/s 00:00

After copying the program, you can now execute the program on the target board. Enter the following command:

developer@ldc:~# ssh root@10.0.6.221 ./hello

root@10.0.6.221's password:
Hello EMAC OE!

Linux Filesystem Organization

In order to prevent confusion and promote portability, a standard was created for the organization of the Linux filesystem. To ensure future portability of software created today, promote maintainability of software, and ensure proper utilization of available storage on an embedded machine, this standard should be followed as much as possible. This document covers parts of the standard and gives information about the customizations made to it by EMAC OE to accommodate embedded hardware. A link is provided to the standards document which covers the organization of the Linux filesystem at the end of this document. For more information visit the Linux Filesystem Organization page.

EMAC recommends /usr/local/bin as the location for software you deploy.

/usr/local/bin

NOTE

It is important to pay attention to the filesystem structure in order to ensure that your application will work as expected when the filesystem is in production. Reasons for this include: Only certain directories, such as /var/ and /tmp/, are writeable when the filesystem is read-only. Only certain directories should contain executables, such as /bin/, /usr/bin/, and /usr/local/bin/. Following this directory structure properly will make it easier to port your software to a newer release of EMAC OE later on.

Remote Debugging

Sometimes a program has no technical errors that cause the compile to fail, but fails to meet the developer's expectations when run. This is typically due to algorithm or data structure design errors which can be difficult to find with just visual inspection of the code. Because of this, it can be beneficial to run a debugger targeting the executable process. Debugging is the process of watching what is going on inside of another program while it is running. When a program is compiled with debug symbols included in the binary, it is possible to observe the source code and corresponding assembly code while running the debugger.

WARNING!

The above paragraph comes across as sounding like the article is targeted towards a beginner programmer. The reader may be a beginner to cross compiling and to embedded, but is very unlikely to be a beginner programmer. Rather than describing what a debugger is, it would be better to tell them about their ability to remotely debug their software over Ethernet using gdb, because that's something that could be new (and cool) to them. Also, they're going to want to know that there are both commandline and GUI versions of the debugger available (most of them will only care about the GUI version, but not all) and that the EMAC provided Qt Creator is all set up for remote debugging (once it knows what IP address to point to).

When working with embedded systems the binary is usually compiled on a development machine with a different CPU architecture than what is on the target machine. This can be a problem when, as is typically the case, the target machine lacks the system resources to run a debugger. In these cases, it is possible to use the GNU debugger, or GDB, on the development machine to remotely debug the target machine provided it has a program called gdbserver. All EMAC OE builds are packaged with gdbserver to simplify the setup process for developers.

For more information visit the Remote Debugging EMAC OE SDK Projects with gdbserver page.

Examples

Hello World System Log Example

This example will print Hello EMAC OE! to the syslog facility as well as the console. This will allow you to log, debug, and send status messages to the system logger.

To compile and run this program, see the sections above.

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <syslog.h>

int main(int argc, char** argv)
{    
    char message[] = "Hello EMAC OE!";

    openlog("slog", LOG_PID|LOG_CONS, LOG_USER);
    syslog(LOG_INFO, "%s", message);
    closelog();    

    printf("%s\n", message);

    return 0;
}

This is extremely useful because it allows you to save a record of the output that you might not see first hand.

To verify the output of the program went into syslog, enter the following command:

developer@ldc:~# tail /var/log/syslog

Apr 7 14:10:06 ENG-26-LX dhclient: DHCPACK of 10.0.6.237 from 10.0.2.1
Apr 7 14:10:06 ENG-26-LX dhclient: bound to 10.0.6.237 -- renewal in 3306 seconds.
Apr 7 14:17:01 ENG-26-LX CRON[21193]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
Apr 7 14:54:41 ENG-26-LX hpcups[21266]: prnt/hpcups/HPCupsFilter.cpp 689: First raster data plane..
Apr 7 14:55:31 hpcups[21266]: last message repeated 3 times
Apr 7 15:05:12 ENG-26-LX dhclient: DHCPREQUEST of 10.0.6.237 on eth0 to 10.0.2.1 port 67
Apr 7 15:05:12 ENG-26-LX dhclient: DHCPACK of 10.0.6.237 from 10.0.2.1
Apr 7 15:05:12 ENG-26-LX dhclient: bound to 10.0.6.237 -- renewal in 3559 seconds.
Apr 7 15:17:01 ENG-26-LX CRON[21302]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
Apr 7 15:27:08 ENG-26-LX slog[21375]: Hello EMAC OE!

As you can see on the bottom line, your program output has been recorded and date stamped in syslog.

For more information on system logging visit the System Logging page.

Further Information

Where to Go Next

• Getting Started With Qt Creator

Pages with Related Content

• System Log In
• Serial Connections
• Network_Connections
• System Log In
• Remote Debugging EMAC OE SDK Projects with gdbserver
• Linux Filesystem Organization
• CMake
• Remote Debugging EMAC OE SDK Projects with gdbserver
• System Logging