Difference between revisions of "Getting Started with the EMAC OE SDK"

From wiki.emacinc.com
Jump to: navigation, search
Line 10: Line 10:
 
<!-- /****************************************  Page Description Text  ****************************************/ -->
 
<!-- /****************************************  Page Description Text  ****************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
<span style="background:#00FF00;color:#FF0000;font-size:300%">'''''Put the page description text here.'''''</span>
+
<span style="background:#00FF00;color:#FF0000;font-size:300%">'''''A Basic tutorial for using the EMAC OE SDK.'''''</span>
  
 
__TOC__
 
__TOC__
Line 21: Line 21:
  
 
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. Follow the links below to get started building and running the example projects on the target hardware.
 
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. Follow the links below to get started building and running the example projects on the target hardware.
 +
 +
For more information on using Qt Creator with the EMAC SDK visit the [[Getting_Started_With_Qt_Creator |Getting Started With Qt Creator]] page.
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*****************************************  Using/Working With  ******************************************/ -->
 
<!-- /*****************************************  Using/Working With  ******************************************/ -->
Line 35: Line 37:
 
{{cli | oemntrw -r | hostname=ipac9x25}}
 
{{cli | oemntrw -r | hostname=ipac9x25}}
  
===Transferring Files===
+
=== Transferring Files ===
 
The command line syntax for transferring a file using the SSH protocol is <code>scp file user@host:/directory</code>. 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 <code>/home</code> directory of a system with the IP address 10.0.6.221, enter the following command:
 
The command line syntax for transferring a file using the SSH protocol is <code>scp file user@host:/directory</code>. 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 <code>/home</code> directory of a system with the IP address 10.0.6.221, enter the following command:
 
{{cli | username=developer | hostname=ldc | scp example.text root@10.0.6.221:/home }}
 
{{cli | username=developer | hostname=ldc | scp example.text root@10.0.6.221:/home }}
  
 +
=== Remote Execution ===
 +
SSH can also be used to execute programs on remote systems without logging in. The syntax for SSH remote execution is <code>ssh user@host "my_command -args file"</code>. For example, to run the program ''hello_world'' with the ''-hi'' flags on a system with the IP address of 10.0.6.221, enter the following command:
 +
{{cli | username=developer | hostname=ldc | ssh root@10.0.6.221 "/path/to/executable -args" }}
 +
<br />
 +
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.
 +
 +
=== 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:
 +
{{cli | username=developer | hostname=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:
 +
{{clo|indent=2}}
 +
{{clio | username=developer | hostname=ldc | ls -l hello* }}
 +
-rwxrwxr-x 1 bserrano bserrano 9583 Apr  6 12:45 hello <br />
 +
-rwxr-xr-x 1 bserrano bserrano  129 Apr  6 12:28 hello.c
 +
{{clos}}
 +
 +
To run the program, enter the following command:
 +
{{clo|indent=2}}
 +
{{clio | username=developer | hostname=ldc | ./hello }}
 +
Hello EMAC OE!
 +
{{clos}}
 +
 +
OR
 +
{{clo|indent=2}}
 +
{{clio | username=developer | hostname=ldc | /path/to/hello }}
 +
Hello EMAC OE!
 +
{{clos}}
 +
 +
==== Target Board Compiling ====
 +
{{note|In these examples we are using the Ipac-9x25 board. So depending on your board architecture it will determine which file needs to be source. These files come from the EMAC SDK toolchain.}}
 +
 +
To compile on the target board, you must <code>source</code> the <code>environment-setup-armv5te-emac-linux-gnueabi</code> file.
 +
{{cli | username=developer | hostname=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:
 +
{{cli | username=developer | hostname=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 <code>scp</code>. Enter the following command:
 +
{{clo|indent=2}}
 +
{{clio | username=developer | hostname=ldc | scp hello root@10.0.6.221: }}
 +
root@10.0.6.221's password:
 +
hello                                        100% 9583    9.4KB/s  00:00   
 +
{{clos}}
 +
 +
After copying the program, you can now execute the program on the target board. Enter the following command:
 +
{{clo|indent=2}}
 +
{{clio | username=developer | hostname=ldc | ssh root@10.0.6.221 ./hello}}
 +
root@10.0.6.221's password: <br />
 +
Hello EMAC OE!
 +
{{clos}}
 +
 +
=== 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 | Linux Filesystem Organization]] page.
 +
 +
EMAC recommends ''/usr/local/bin'' as the location for software you deploy.
 +
 +
/usr/local/bin
  
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.
+
<cl>
 +
1. 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. Reason for this:
 +
i. 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.
 +
</cl>
 +
 
 +
=== 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_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver]] page.
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
Line 46: Line 125:
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
{{:Templateimpl:examples | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
 
{{:Templateimpl:examples | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
 +
=== Hello World System Log Example ===
 +
This example will print <code>Hello EMAC OE!</code> to the syslog facility as well as the console. This will allow you to log, debug, and send status messages to the system logger.
 +
 +
<syntaxhighlight lang="c">
 +
#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);
<!-- /******************************************     Conclusion      ******************************************/ -->
+
 
<!-- /*********************************************************************************************************/ -->
+
     return 0;
{{:Templateimpl:conclusion | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
+
}
 +
</syntaxhighlight>
 +
 
 +
This is extremely useful because it allows you to save a record of the output that you might not see first hand.
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
Line 56: Line 154:
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
{{:Templateimpl:moreinfo | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
 
{{:Templateimpl:moreinfo | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
*  
+
* [[Getting_Started_With_Qt_Creator |Getting Started With Qt Creator]]
  
 
{{:Templateimpl:whatnext | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
 
{{:Templateimpl:whatnext | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
*
+
* [[System_Log_In | System Log In]]
 +
* [[Linux_Filesystem_Organization | Linux Filesystem Organization]]
 +
* [[Remote_Debugging_EMAC_OE_SDK_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver]]

Revision as of 14:12, 7 April 2015

TODO: {{#todo: InProgress (03.31.2015-13:42->BS+)|Brian Serrano|OE 5.0,BS}}

A Basic tutorial for using the EMAC OE SDK.

General Information

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. Follow the links below to get started building and running the example projects on the target hardware.

For more information on using Qt Creator with the EMAC SDK visit 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. 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.

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

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

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_world 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"


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.

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. So depending on your board architecture it will determine which file needs to be source. These files come from the EMAC SDK toolchain.


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 ./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


  1. 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. Reason for this:

    1. Only certain directories, such as /var/ and /tmp/, are writeable when the filesystem is read-only.

    2. Only certain directories should contain executables, such as /bin/, /usr/bin/, and /usr/local/bin/.

    3. 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.

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.

#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.

Further Information

Where to Go Next
Pages with Related Content