Getting Started with the EMAC OE SDK
| WARNING! |
| Now is a good time to come up with keywords for the SEO tag. |
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.
| WARNING! |
| The following sentence isn't very compelling. I'd probably click back and look for a different page after reading that sentence. Maybe something like, "This page 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." |
This guide consists of a simple hello.c source file.
Contents
General Information
| WARNING! |
| We primarily distribute the SDK with our apt repository as a deb file for Ubuntu. We also provide a tarball they can extract, but we recommend the deb because that's the only version we officially support. I would reword this sentence to reflect that. |
The EMAC Open Embedded SDK is distributed in an archive that can be extracted and used from a Linux terminal or from within an integrated development environment such as Qt Creator.
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.
| WARNING! |
| Using commanding language ("Follow the links to do this") sounds a bit unfriendly when talking to customers (as opposed to internal documentation). We've tried to steer away from that in our documentation as much as possible. Instead, we try to phrase sentences in a friendly, informative way. I reworded two sentences above to show what I mean. |
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. EMAC OE Linux allows login from getty, and SSH (Secure Shell). A getty uses the serial connection or console while SSH utilizes a network connection. For more information visit the System Log In page.
| WARNING! |
| This is too abrupt. It feels like a paragraph or more is missing. You're assuming the reader already knows how to establish a physical connection. You need to either document how to do so here, or provide a link for information on how to do this. Remember, pages which are found via google need to stand on their own, since it may be the only page on our site that a potential customer will ever see. If they like it, they may come back and become a customer. If it leaves them hanging, they probably won't. It may be annoying to have to cater to that idea with every document we write, but it really is very important. |
Setting up the Filesystem Read-Write
To set up the root filesytem read-write, enter the following into the terminal:
root@ipac9x25:~# oemntrw To revert back the root filesytem to read-only, enter the following into the terminal:
root@ipac9x25:~# oemntrw -r
| WARNING! |
| Why would they want to do this? Because our filesystems are mounted read-only by default, which means they're not going to be able to put their program on the board unless they make it read-write first? There's a good chance they don't know that. Let them know. ;) |
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
Be aware that this copy operation will fail if the filesystem on the remote machine is mounted read-only, which is the default on most EMAC systems.
| WARNING! |
| (I'm only using the warning box so it stands out, and so you can remove it easily). It would be nice to let the reader know that they can leave off the path after the : if they want the file to go directly into their home directory. I like that trick a lot because it saves me a lot of typing. They'll probably like it too. Also, be careful where you put comments/notes. I moved the line above this box from below, because it was attached to the remote execution command before. |
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"
Basic Compiling
Host Machine Compiling
Create a file called hello.c using a text editor such as vi, vim, nano, or gedit.
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
| 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 is the manual way to do it, and only works well for ultra simple programs which only have one source file. Our customers are professional programmers, which means they will almost never have only one source file. We put a lot of work into CMake to make the cross compiling process much easier, and Klint created a tool to generate the CMake files automatically for a project. This is an important selling point for EMAC (everyone hates doing this by hand the manual way), so this is the method that should be documented first. Here's the script in our version control system: http://gitlab.emacinc.com/oe/cmake-new-project We will have a deb package in apt for this when we get a chance to make it, or we may incorporate it into one of our existing packages (like the tools package). You can leave a stub for how to install it before describing it. |
To compile on 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 ./helloroot@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:
|
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.
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.
| WARNING! |
| I removed the GPL copyright because this code should be unlicensed and free for the customers to use any way they want. Virtually no customer is going to want to release their source code to the public, so pushing the GPL on them can give the wrong impression. |
#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 program went into the syslog, enter the following command:
developer@ldc:~# tail /var/log/syslogApr 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 the syslog.
| WARNING! |
| I think we have a page which talks more about the system logging facility. If not, we do at least have it on our TODO list of pages to write. See if you can find that page, and link to it here. If we don't have it yet, please create a stub page for it and link to it here (using the template, of course). |
