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

From wiki.emacinc.com
Jump to: navigation, search
(Reviewed and updated using the Update 2019 version and a few additions of links for clarity and flow)
 
(39 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{todo| Buggy (03.31.2015-13:42->BS+), (04.08.2015-15:00->BS+);(04.09.15-14:00->MD+) |Brian Serrano| project=OE 5.0,BS,MD,SEOKWREV}}
+
{{todo| Complete (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+);(04.29.2015-16:00->BS+);(04.29.2015-17:30->MD+);(04.30.2015-15:30->KY+); (07.22.2015-11:00->BS+)(10.07.2015-16:32->KY+)|Brian Serrano| project=OE 5.0,BS,MD,Complete,KY}}
 
{{#seo:
 
{{#seo:
 
|title=Getting Started with the EMAC OE SDK
 
|title=Getting Started with the EMAC OE SDK
 
|titlemode=append
 
|titlemode=append
|keywords=EMAC SDK,Hello World Example,Target Board
+
|keywords=EMAC SDK,Cross compiling, ARM Target Compiling, CMake Build System, CMake Cross Compiling, CMake, CMake Arm
|description=A basic tutorial for using the EMAC OE SDK
+
|description=A basic tutorial for using the EMAC OE SDK.
 
}}
 
}}
{{warning|Now is a good time to come up with keywords for the SEO tag.}}
+
 
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /****************************************  Page Description Text  ****************************************/ -->
 
<!-- /****************************************  Page Description Text  ****************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 +
 
<span style="background:#00FF00;color:#FF0000;font-size:300%"></span>
 
<span style="background:#00FF00;color:#FF0000;font-size:300%"></span>
 +
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.
 +
  
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.
 
 
__TOC__
 
__TOC__
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
<!-- /*****************************************  General Information *****************************************/ -->
+
<!-- /*****************************************  Using/Working With ******************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
{{:Templateimpl:geninfo | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}
+
{{:Templateimpl:using | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}  
{{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 primarily distributed with our apt repository as a deb file for Ubuntu. EMAC also provides a tarbell you can extract, but recommends the deb file because it's the only version EMAC officially supports.
 
  
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 |Getting Started With Qt Creator]] page.
+
=== Installing EMAC SDK ===
{{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.}}
+
A Linux developer system is required to install the EMAC software development kit.
<!-- /*********************************************************************************************************/ -->
+
 
<!-- /*****************************************  Using/Working With  ******************************************/ -->
+
For those without a Linux developer system we recommend downloading Oracle VM VirtualBox and installing EMAC's pre-configured Linux Ubuntu virtual machine. All steps involved can be found here: <br />
<!-- /*********************************************************************************************************/ -->
+
[[Getting_Started_With_EMAC_Virtual_LDC | Set up virtual machine with EMAC_OE_SDK pre-installed ]] <br />
{{:Templateimpl:using | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}  
+
'''OR''' <br />
 +
Those with a Linux developer system already configured can follow the below steps: <br />
 +
[[Installing_EMAC_OE_5.0_SDK | SDK Install]] <br />
 +
 
 +
 
 +
 
 +
{{note|The most current EMAC_OE_SDK release is version 5.1, all higher versions should be disregarded.}}
 
=== Connecting to a Target Board ===
 
=== 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 [[Serrial_Connections |Serial Connections]] and [[Network_Connections |Network Connections]] page.
 
  
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 | System Log In]] page.
+
Primarily a board is connected to through it's debug serial port. If it also connected to a network and the IP address is known, ssh can be used to connect as well. More information on establishing a physical connection to a board is available on the [[Serial_Connections |Serial Connections]] and [[Network_Connections |Network Connections]] 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.}}
+
 
 +
The next step after establishing a physical connection to the board is logging inFor more information visit the [[System_Log_In | System Log In]] page.
  
=== Setting up the Filesystem Read-Write ===
+
=== Setting the Filesystem to Read-Write ===
The filesystems on the remote machines are mounted read-only by default. In order to put your program on the board, you need to make the filesystem 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|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 set up the root filesytem read-write, enter the following into the terminal:  
+
To remount the root filesytem in read-write mode, enter the following into the terminal:  
 
{{cli | oemntrw | hostname=ipac9x25}}
 
{{cli | oemntrw | hostname=ipac9x25}}
  
{{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. ;)}}
+
{{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 ===
 
=== 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>/usr/bin</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:/usr/bin/ }}
 +
 
 +
Alternatively, you can leave off the path after the colon if you want the file to go directly into the root user's home directory.
 +
 
 +
{{cli | username=developer | hostname=ldc | scp example.text root@10.0.6.221: }}
 +
 
 +
=== 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>. The following is an example of a command to run a program on a board with the IP address ''10.0.6.221''.
 +
 
 +
{{cli | username=developer | hostname=ldc | ssh root@10.0.6.221 "/path/to/executable -args" }}
 +
 
 +
 
 +
=== Basic Compiling ===
 +
The two subsections below show the two common options for how to compile source code. The first subsection demonstrates how to use the EMAC [[ #CMake_Compiling| CMake ]] tool, while the second subsection demonstrates how to compile c code [[ #Manual_Compiling | manually ]]. Another helpful link if you are looking to create a new project with CMake: [[ Creating_a_New_EMAC_OE_SDK_Project_with_CMake | Creating a New EMAC OE SDK Project with CMake ]]
 +
 
 +
==== CMake Compiling ====
 +
===== Host Machine Compiling =====
 +
 
 +
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 <tt>arm</tt> 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.
 +
{{clo}}
 +
{{clio | username=developer | hostname=ldc | pwd=~ |cd projects }}
 +
{{clio | username=developer | hostname=ldc | pwd=~/projects | 1 = export PATH=/opt/emac/5.1/bin:$PATH}}
 +
{{clio | username=developer | hostname=ldc | pwd=~/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 <br />
 +
 
 +
-- Creating new project directory... <br />
 +
-- Creating new source file... <br />
 +
-- Building custom CMakeLists.txt file... <br />
 +
-- Done. <br />
 +
 
 +
Do you want to create a build directory for this project? (y/n) y <br />
 +
 
 +
-- Creating build directory... <br />
 +
 
 +
Do you want to run cmake for this project? (y/n) y <br />
 +
 
 +
-- Using system compiler <br />
 +
-- The C compiler identification is GNU 4.8.2 <br />
 +
-- The CXX compiler identification is GNU 4.8.2 <br />
 +
-- Check for working C compiler: /usr/bin/cc <br />
 +
-- Check for working C compiler: /usr/bin/cc -- works <br />
 +
-- Detecting C compiler ABI info <br />
 +
-- Detecting C compiler ABI info - done <br />
 +
-- Check for working CXX compiler: /usr/bin/c++ <br />
 +
-- Check for working CXX compiler: /usr/bin/c++ -- works <br />
 +
-- Detecting CXX compiler ABI info <br />
 +
-- Detecting CXX compiler ABI info - done <br />
 +
-- Configuring done <br />
 +
-- Generating done <br />
 +
-- Build files have been written to: /home/developer/projects/hello_emac/hello_emac-build <br />
 +
 
 +
Do you want to compile this project? (y/n) y
 +
 
 +
Scanning dependencies of target hello_emac <br />
 +
[100%] Building C object CMakeFiles/hello_emac.dir/hello.c.o <br />
 +
Linking C executable hello_emac <br />
 +
[100%] Built target hello_emac <br />
 +
{{clos}}
 +
 
 +
The executable, in this case,  is now inside the <code> hello_emac/hello_emac-build </code> directory.
 +
 
 +
===== Target Machine Compiling =====
 +
 
 +
The CMake project script has now made a project directory that contains the following:
 +
* CMakeLists.txt
 +
* Source code file (''hello.c'' in this case)
 +
* ''README'' file
 +
* Desktop Build Directory (''hello_emac-build'' in this case)
 +
 
 +
The ''CMakeLists.txt'' contains the required information to automatically create a ''Makefile'' for a given architecture.  This was created by the EMAC <tt>oe_init_project</tt> script, and will need to be modified over time as a project grows.  The comments in the file generated by the EMAC tool will provide a good starting point for how to add additional source files and how to perform other common tasks related to maintaining your CMake build system as your project grows.  The CMake project provides extensive documentation on how to work with these files.
 +
 
 +
The source code file generated by the script (''hello.c'') contains a basic Hello World style program.
 +
 
 +
The ''README'' file contains more information on using ''CMake'' with the EMAC 5.X SDK.
 +
 
 +
The Desktop Build Directory (''hello_emac-build'') contains the executable ''hello_emac'', the ''Makefile'', and various cache files.  These were automatically created by CMake and by the build system, and can be recreated at any time.
 +
 
 +
It is useful to have a Desktop Build Directory because it is easier (in the beginning) to use the desktop to verify all code changes before cross-compiling for a target board. This will be useful until the application under development depends upon resources which are only available on the target hardware, such as certain devices drivers or the touchscreen (if so equipped).
 +
 
 +
Use the following steps to cross-compile the project and send it to a target board.
 
<br />
 
<br />
Alternatively, you can leave of the path after the ':' if you want the file to go directly into the home directory.
 
{{cli | username=developer | hostname=ldc | scp example.text root@10.0.6.221: }}
 
 
<br />
 
<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.
+
<cl>
 +
1. In a terminal, navigate to the base directory of the project.
 +
{{note | If the target board being used is <tt>x86</tt>, then change all occurrences of <tt>arm</tt> in the following sections below to <tt>x86</tt>.}}
 +
* Create a build directory for cross compiling.
 +
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | mkdir hello_emac-build-arm }}
 +
* Change directories into the newly created directory.
 +
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | cd hello_emac-build-arm }}
 +
* Run cmake using the target architecture.
 +
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | 1 = cmake .. -DARCH:STRING=arm }}
 +
* Compile the code using make.
 +
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | make }}
  
{{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.
+
The <code> make </code> command creates the target executable in the <code> hello_emac-build-arm </code> directory.
 +
* Now copy the executable to the target board. Use any of the options listed under the [[ #Transferring_Files | Transferring Files ]] section.
  
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.}}
+
The executable is now located on the target device at the designated transfer directory. It now can be run remotely (covered [[#Remote_Execution | here]]) OR from the target device by navigating to the transfer directory and issuing the run command (./executable_name).
=== Remote Execution ===
+
</cl>
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'' with the ''-hi'' flags on a system with the IP address of 10.0.6.221, enter the following command:
+
<br />
{{cli | username=developer | hostname=ldc | ssh root@10.0.6.221 "/path/to/executable -args" }}
+
<br />
  
 +
==== Manual Compiling ====
 +
===== Host Machine Compiling =====
 +
<br />{{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.}}
  
=== Basic Compiling ===
+
Create a file called hello.c using a text editor such as vi, nano, or gedit. Then copy and paste the source code from the [[ #Hello_World_System_Log_Example | Hello World System Log Example ]] section in the text editor of your choice.
==== 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:
+
Once you've created and saved the file with the source code, use the following syntax to compile the program called hello.c:
 
{{cli | username=developer | hostname=ldc | gcc -o hello 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.  
+
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:
 
To verify this, enter the following command:
{{clo|indent=2}}
+
{{clo}}
 
{{clio | username=developer | hostname=ldc | ls -l hello* }}
 
{{clio | username=developer | hostname=ldc | ls -l hello* }}
 
-rwxrwxr-x 1 bserrano bserrano 9583 Apr  6 12:45 hello <br />
 
-rwxrwxr-x 1 bserrano bserrano 9583 Apr  6 12:45 hello <br />
Line 79: Line 177:
  
 
To run the program, enter the following command:
 
To run the program, enter the following command:
{{clo|indent=2}}
+
{{clo}}
 
{{clio | username=developer | hostname=ldc | ./hello }}
 
{{clio | username=developer | hostname=ldc | ./hello }}
 
Hello EMAC OE!
 
Hello EMAC OE!
Line 85: Line 183:
  
 
OR
 
OR
{{clo|indent=2}}
+
{{clo}}
 
{{clio | username=developer | hostname=ldc | /path/to/hello }}
 
{{clio | username=developer | hostname=ldc | /path/to/hello }}
 
Hello EMAC OE!
 
Hello EMAC OE!
 
{{clos}}
 
{{clos}}
 +
<br />
 +
<br />
  
 +
===== Target Board Compiling =====
  
==== Target Board Compiling ====
+
To compile for the target board, you must <code>source</code> the <code>environment-setup-armv5e-emac-linux-gnueabi</code> file.
{{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.}}
+
{{cli | username=developer | hostname=ldc | source /opt/emac/5.1/environment-setup-armv5e-emac-linux-gnueabi }}
{{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 <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:
 
Once you are in the directory with the source file, enter the following command:
Line 104: Line 201:
  
 
After sourcing the file, copy the program over to the target board using <code>scp</code>. Enter the following command:
 
After sourcing the file, copy the program over to the target board using <code>scp</code>. Enter the following command:
{{clo|indent=2}}
+
{{clo}}
 
{{clio | username=developer | hostname=ldc | scp hello root@10.0.6.221: }}
 
{{clio | username=developer | hostname=ldc | scp hello root@10.0.6.221: }}
 
root@10.0.6.221's password:  
 
root@10.0.6.221's password:  
 +
 
hello                                        100% 9583    9.4KB/s  00:00     
 
hello                                        100% 9583    9.4KB/s  00:00     
 
{{clos}}
 
{{clos}}
  
 
After copying the program, you can now execute the program on the target board. Enter the following command:
 
After copying the program, you can now execute the program on the target board. Enter the following command:
{{clo|indent=2}}
+
{{clo}}
 
{{clio | username=developer | hostname=ldc | ssh root@10.0.6.221 ./hello}}
 
{{clio | username=developer | hostname=ldc | ssh root@10.0.6.221 ./hello}}
 
root@10.0.6.221's password: <br />  
 
root@10.0.6.221's password: <br />  
 
Hello EMAC OE!
 
Hello EMAC OE!
 
{{clos}}
 
{{clos}}
 +
<br />
 +
<br />
  
=== Linux Filesystem Organization ===
+
=== Remote Debugging ===
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
 
 
 
{{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:
 
<cl>
 
1. 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 ===
+
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 (<tt>gdb</tt>) on the development machine to remotely debug the target machine provided it has a flavor-matched version of a program named <tt>gdbserver</tt>. All EMAC OE builds are packaged with a flavor-matched <tt>gdbserver</tt> to simplify the setup process for developers.
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.
+
{{note | A flavor-matched <tt>gdbserver</tt> is one which is built against the same source code revision as the <tt>gdb</tt> client for your desktop, because <tt>gdb</tt> does not have a stable interface for attaching to the <tt>gdbserver</tt>. In fact, the interface changes slightly with almost every release, so if you find yourself having difficulty getting <tt>gdb</tt> and <tt>gdbserver</tt> to communicate with each other, make sure they're the exact same version before trying any other debugging steps.}}
  
For more information visit the [[Remote_Debugging_EMAC_OE_SDK_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver]] page.
+
For more information visit the [[Remote_Debugging_EMAC_OE_SDK_Projects_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver]] page.
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
Line 142: Line 229:
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
{{: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 ===
 
=== 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.
 
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.
Line 147: Line 235:
 
To compile and run this program, see the sections above.
 
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.}}
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
 
#include <stdio.h>
 
#include <stdio.h>
Line 170: Line 257:
 
This is extremely useful because it allows you to save a record of the output that you might not see first hand.
 
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:
+
To verify the output of the program went into syslog, enter the following command:
{{clo|indent=2}}
+
{{clo}}
 
{{clio | username=developer | hostname=ldc | tail /var/log/syslog}}
 
{{clio | username=developer | hostname=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<br />
 
Apr  7 14:10:06 ENG-26-LX dhclient: DHCPACK of 10.0.6.237 from 10.0.2.1<br />
Line 185: Line 272:
 
{{clos}}
 
{{clos}}
  
As you can see on the bottom line, your program output has been recorded and date stamped in the syslog.
+
As you can see on the bottom line, your program output has been recorded and date stamped in 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).}}
+
 
 +
For more information on system logging visit the [[System_Logging| System Logging ]] page.
 +
 
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /******************************************  More Information  *****************************************/ -->
 
<!-- /******************************************  More Information  *****************************************/ -->
Line 194: Line 283:
  
 
{{: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 }}
 +
* [[ Creating_a_New_EMAC_OE_SDK_Project_with_CMake | Creating a New EMAC OE SDK Project with CMake ]]
 +
* [[EMAC_Example_Projects | EMAC Example Projects]]
 +
* [[Serial_Connections | Serial Connections ]]
 +
* [[Network_Connections | Network_Connections ]]
 +
* [[Remote_Debugging_EMAC_OE_SDK_Projects_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver ]]
 +
* [[Linux_Filesystem_Organization | Linux Filesystem Organization]]
 
* [[System_Log_In | System Log In]]
 
* [[System_Log_In | System Log In]]
* [[Linux_Filesystem_Organization | Linux Filesystem Organization]]
+
* [[System_Logging | System Logging ]]
* [[Remote_Debugging_EMAC_OE_SDK_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver]]
 

Latest revision as of 14:03, 8 September 2020

TODO: {{#todo: Complete (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+);(04.29.2015-16:00->BS+);(04.29.2015-17:30->MD+);(04.30.2015-15:30->KY+); (07.22.2015-11:00->BS+)(10.07.2015-16:32->KY+)|Brian Serrano|OE 5.0,BS,MD,Complete,KY}}


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.


Getting Started with the EMAC OE SDK

Installing EMAC SDK

A Linux developer system is required to install the EMAC software development kit.

For those without a Linux developer system we recommend downloading Oracle VM VirtualBox and installing EMAC's pre-configured Linux Ubuntu virtual machine. All steps involved can be found here:
Set up virtual machine with EMAC_OE_SDK pre-installed
OR
Those with a Linux developer system already configured can follow the below steps:
SDK Install




NOTE
The most current EMAC_OE_SDK release is version 5.1, all higher versions should be disregarded.

Connecting to a Target Board

Primarily a board is connected to through it's debug serial port. If it also connected to a network and the IP address is known, ssh can be used to connect as well. More information on establishing a physical connection to a board is available on the Serial Connections and Network Connections page.

The next step after establishing a physical connection to the board is logging in. 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 /usr/bin 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:/usr/bin/

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

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

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". The following is an example of a command to run a program on a board with the IP address 10.0.6.221.

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


Basic Compiling

The two subsections below show the two common options for how to compile source code. The first subsection demonstrates how to use the EMAC CMake tool, while the second subsection demonstrates how to compile c code manually . Another helpful link if you are looking to create a new project with CMake: Creating a New EMAC OE SDK Project with CMake

CMake Compiling

Host Machine Compiling

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:~# cd projects
developer@ldc:~/projects# export PATH=/opt/emac/5.1/bin:$PATH
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

The CMake project script has now made a project directory that contains the following:

  • CMakeLists.txt
  • Source code file (hello.c in this case)
  • README file
  • Desktop Build Directory (hello_emac-build in this case)

The CMakeLists.txt contains the required information to automatically create a Makefile for a given architecture. This was created by the EMAC oe_init_project script, and will need to be modified over time as a project grows. The comments in the file generated by the EMAC tool will provide a good starting point for how to add additional source files and how to perform other common tasks related to maintaining your CMake build system as your project grows. The CMake project provides extensive documentation on how to work with these files.

The source code file generated by the script (hello.c) contains a basic Hello World style program.

The README file contains more information on using CMake with the EMAC 5.X SDK.

The Desktop Build Directory (hello_emac-build) contains the executable hello_emac, the Makefile, and various cache files. These were automatically created by CMake and by the build system, and can be recreated at any time.

It is useful to have a Desktop Build Directory because it is easier (in the beginning) to use the desktop to verify all code changes before cross-compiling for a target board. This will be useful until the application under development depends upon resources which are only available on the target hardware, such as certain devices drivers or the touchscreen (if so equipped).

Use the following steps to cross-compile the project and send it to a target board.

  1. In a terminal, navigate to the base directory of the project.



    NOTE
    If the target board being used is x86, then change all occurrences of arm in the following sections below to x86.
  2. Create a build directory for cross compiling.

    developer@ldc:~/projects/hello_emac# mkdir hello_emac-build-arm
  3. Change directories into the newly created directory.

    developer@ldc:~/projects/hello_emac# cd hello_emac-build-arm
  4. Run cmake using the target architecture.

    developer@ldc:~/projects/hello_emac/hello_emac-build-arm# cmake .. -DARCH:STRING=arm
  5. Compile the code using make.

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

    The make command creates the target executable in the hello_emac-build-arm directory.

  6. Now copy the executable to the target board. Use any of the options listed under the Transferring Files section.

    The executable is now located on the target device at the designated transfer directory. It now can be run remotely (covered here) OR from the target device by navigating to the transfer directory and issuing the run command (./executable_name).



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


Create a file called hello.c using a text editor such as vi, nano, or gedit. Then copy and paste the source code from the Hello World System Log Example section in the text editor of your choice.

Once you've created and saved the file with the source code, 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-armv5e-emac-linux-gnueabi file.

developer@ldc:~# source /opt/emac/5.1/environment-setup-armv5e-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!



Remote Debugging

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 (gdb) on the development machine to remotely debug the target machine provided it has a flavor-matched version of a program named gdbserver. All EMAC OE builds are packaged with a flavor-matched gdbserver to simplify the setup process for developers.



NOTE
A flavor-matched gdbserver is one which is built against the same source code revision as the gdb client for your desktop, because gdb does not have a stable interface for attaching to the gdbserver. In fact, the interface changes slightly with almost every release, so if you find yourself having difficulty getting gdb and gdbserver to communicate with each other, make sure they're the exact same version before trying any other debugging steps.


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
Pages with Related Content