Monday, May 18, 2015

BeagleBone Black Development Part 6 - Remote Application Debugging With Eclipse

This tutorial shows how to debug a BeagleBone Black  application remotely using the Eclipse IDE. This is similar to a post I made last year but with updates for BeagleBone Black Rev. C and Debian Jessie on the host machine and on the board.

This is part six in a series of tutorials that show how to develop for Beaglebone Black starting from a new install of Debian Jessie on a host machine in Part 1, and Part 2.  Part 3 covers cross-tool setup for BeagleBone BlackBeagleBone Black kernel build steps are in Part 4 and installing Linux to eMMC using Micro SD is covered in part 5.

6.1 Install GDB server on the BeagleBone Black


A GDB server can use any IP connection to debug.  You can use ethernet port (eth0), the USB device port (usb0), a USB to Ethernet adapter on the USB host port (eth1) or a USB to WIFI device.  


See the USB gadget section of Beaglebone Black - Linux on ARM to set up usb0.
https://eewiki.net/display/linuxonarm/BeagleBone+Black#BeagleBoneBlack-usbgadget


To use a USB-to-ethernet device in the host port, you need to build a kernel configured with drivers for your device.  The drivers can be found in menuconfig in Device drivers>Network device support>USB Network Adapters.


Connect the FTDI USB to serial port and log into the console and power up the Beaglebone Black.


The following commands with usernames that end with @arm are executed in the serial terminal program on the BeagleBone Black, not on the host used to cross-compile the kernel.


debian@arm:~$ sudo apt-get update
debian@arm:~$ sudo apt-get install gdbserver


6.2 Eclipse IDE Setup on Development Host



Eclipse is a large install package, it will take a little while to complete. Enter these commands on the Linux cross-development host machine.
user@debian:~$ sudo apt-get install eclipse eclipse-cdt  eclipse-cdt-launch-remote


Make a workspace for a test application.
user@debian:~$ mkdir ~/bbb/testws


Start Eclipse from the Applications Menu.  Be patient, the first run takes a long time to load.


Browse to the workspace directory we created and click OK.


Eclipse will come up with a welcome screen.  Select Window, click Open Perspective, Other...
eclipse-open-perspective-other.png
open-c-cpp-perspective.png


Create a new C project using File, New then selecting C Project.


Name the project, select project type Hello World ANSI C Project, select Toolchain Cross GCC, click next.


The next screen asks for basic properties, you can just enter an author and click next.




The Select Configurations window will appear, click on Advanced settings.


In the settings window on the left hand side open up C/C++ Build -> Settings to bring up the Tool Settings tab for the Debug configuration.


Select Cross Settings.  Set the prefix to arm-linux-gnueabihf-  and set the path of the tools we installed earlier (Section 3.2).  If you created the armcc-vars file in that section it will show the path.  
user@debian:~$ cat ~/am335x/armcc-vars
export CC=/home/user/am335x/gcc-linaro-arm-linux-gnueabihf-4.9-2014.09_linux/bin/arm-linux-gnueabihf-
export ARCH=arm
export CROSS_COMPILE=${CC}


In the example file above the prefix is arm-linux-gnueabiehf- and the path to enter is:
/home/user/am335x/gcc-linaro-arm-linux-gnueabihf-4.9-2014.09_linux/bin


Properties for bbb_hello_world.png


Click Apply, then click OK.  You should go back to C Project screen, click Next.C Project Next.png


You should see the next screen asking for the same values we just entered (seems like a bug in eclipse).  Just enter the values for prefix and path one more time and click Finish.
C-project-cross-gcc-command.png


This brings up a workspace with the hello world C source file open.  Build the project using Project menu, Build All and you should see the prefix we entered being used for the tools (gcc).


eclipse-c-project-debug.png


You should not see any errors in the console tab at the bottom of the page.


6.3 Eclipse Remote Connection Setup


The eclipse remote connection will require some changes on the BeagleBone Black.  Make a serial port connection or ssh into a console.


First check the IP address of the port we will use for debugging.  Use the ifconfig command and write down the inet addr shown.  Ethernet port (eth0) information shown below.
debian@arm:~$ sudo ifconfig
[sudo] password for debian:
eth0      Link encap:Ethernet  HWaddr 1c:ba:8c:e1:7f:ae  
         inet addr:192.168.1.140  Bcast:192.168.1.255  Mask:255.255.255.0
         inet6 addr: fe80::1eba:8cff:fee1:7fae/64 Scope:Link
         UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
         RX packets:22706 errors:0 dropped:0 overruns:0 frame:0
         TX packets:205 errors:0 dropped:0 overruns:0 carrier:0
         collisions:0 txqueuelen:1000
         RX bytes:1790146 (1.7 MiB)  TX bytes:23064 (22.5 KiB)
         Interrupt:40


We will need ssh installed and running on the BeagleBone Black for eclipse remote debugging.


Test ssh from the development host machine using the IP address we just found for the port..
user@debian:~$ ssh debian@192.168.1.140


If there are any problems check to make sure an ssh server is installed.
debian@arm:~$ dpkg -s openssh-server
If not install openssh server.
debian@arm:~$ sudo apt-get install openssh-server


If ssh is installed but you have trouble connecting to the board some host key files might be missing.
Check for ‘Could not load host key’ errors in /var/log/auth.log using grep.
debian@arm:~$ grep sshd /var/log/auth.log


If you see this problem you can regenerate the individual keys or just regenerate all by reconfiguring openssh server.
To reconfigure, first delete any existing host keys.
debian@arm:~$ sudo rm /etc/ssh/ssh_host_*
Next, generate all new key files.
debian@arm:~$ dpkg-reconfigure openssh-server


If for some reason you need to regenerate individual keys see Phillip’s Tech Blog: Could not load host key.


Once ssh is working from the host the next step is to add another user to the BeagleBone for the remote debug connection.


Create a user with the same name as the user you created for Debian on the host virtual machine.  In this document the name is just ‘user’ for simplicity.  To be clear, if you are logged in and running eclipse as a user ‘joe’ in the host debian virtual machine, you will create a new user named ‘joe’ on the BeagleBone Black to log in with eclipse ssh for debugging.  This might not be absolutely necessary, but I haven’t found the place to change the remote username, it seems eclipse expects the remote system to have the same username (but allows you to change the remote password).
debian@arm:~$ sudo adduser user
[sudo] password for debian:
Adding user `user' ...
Adding new group `user' (1001) ...
Adding new user `user' (1001) with group `user' ...
Creating home directory `/home/user' ...
Copying files from `/etc/skel' ...
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
Changing the user information for user
Enter the new value, or press ENTER for the default
       Full Name []:
       Room Number []:
       Work Phone []:
       Home Phone []:
       Other []:
Is the information correct? [Y/n] Y
Adding new user `user' to extra groups ...
Adding user `user' to group `dialout' ...
Adding user `user' to group `i2c' ...
Adding user `user' to group `spi' ...
Adding user `user' to group `cdrom' ...
Adding user `user' to group `floppy' ...
Adding user `user' to group `audio' ...
Adding user `user' to group `video' ...
Adding user `user' to group `plugdev' ...
Adding user `user' to group `users' …
debian@arm:~$ exit
logout


Debian GNU/Linux 7 arm ttyO0


default username:password is [debian:temppwd]


arm login: user
Password:
Linux arm 3.8.13-bone70.5 #1 SMP Wed Mar 11 16:37:28 EDT 2015 armv7l


The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.


Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
user@arm:~$


Create a workspace and project directory.
user@arm:~$ mkdir ~/remotews                                                  
user@arm:~$ mkdir ~/remotews/hello                                            
user@arm:~$ chmod a+w ~/remotews/hello/
                       
Next we will set up the host using eclipse.  
On the Eclipse Run menu, click Run Configurations. Select C/C++ Remote Application, press the New launch configuration button.


On the next window the bbb_hello_world Debug run configuration is selected.  On the main tab click New.


run configurations connection new.png


In the New connection window for system type click Linux then next.  


In the next window we will enter the BeagleBone Black IP address for the host name and give a connection name and description.  


Enter the internet address of the port as the Host name.  Click the Verify host name box so it is not checked.


new connection description.png


In the next screen check the box for ssh.files and click Next.




In the Next window click the box for processes.shell.linux and click Next.




On the next screen click ssh.shells and Next.




The next window select ssh.terminals (should be default) and click Finish.




This will return you to the Run Configurations window.
In the Main tab, select BBB Ethernet for Connection then click Properties to the right.




Enter the path to the remote workspace and click OK.  


Next in the Main tab, enter the remote absolute path to the executable application binary.  The absolute path of the executable file will be /home/user/remotews/hello/bbb_hello_world.


Enter ‘chmod +x /home/user/remotews/hello/bbb_hello_world’  in the field ‘commands to execute before application’ to allow the executable to run after it is uploaded to the board.


After both values have been entered click Apply then click Run.  If Run is greyed out so you can’t continue then I have found it easiest to just delete the bbb_hello_world Debug configuration and back up a few steps to creating a new launch configuration.  You won’t have to re-enter the connection information but you need to enter the remote absolute file path and commands to execute again.
Click Run.  Wait a few seconds for the Enter Password window to appear.  Enter the username and password for the BeagleBone Black and click OK.




A secure storage window will appear, choose a password, this is an eclipse feature not required for the ssh connection.


Even though we entered save password above, a ‘Password required’ window might  appear for your ssh connection (possibly only the first time).  Enter the ssh username and password again to connect to the beaglebone black.


If an authenticity of host key warning appears, click Yes.


After a successful run the console will be displayed in the lower Eclipse window.  It will show the output of the remote program.
echo $PWD'>'
chmod +x /home/user/remotews/hello/bbb_hello_world;/home/user/remotews/hello/bbb_hello_world;exit
Last login: Thu Mar 26 15:43:10 2015 from earth
user@arm:~$ echo $PWD'>'
/home/user>
user@arm:~$ chmod +x /home/user/remotews/hello/bbb_hello_world;/home/user/remote ws/hello/bbb_hello_world;exit
!!!Hello World!!!
logout


6.4 Eclipse GDB Debugging Setup


Open a terminal on the host Linux system.  Change to the Debug directory for the project and create an empty .gdbinit file.
user@debian:~$ cd ~/bbb/testws/bbb_hello_world/Debug/
user@debian:~/bbb/testws/bbb_hello_world/Debug$ touch .gdbinit


Open Eclipse, open the Run menu in the menu bar and click Debug Configurations. Select bbb_hello_world Debug under C/C++ Remote Application.


Open the Debugger tab.  This has three tabs for Debugger Options, click the Main tab.
debug configuration main tab.png


Click the Browse button for GDB debugger to find the gdb executable from the host toolchain (arm-linux-gnueabihf-gdb).  
debug browse gdb.png
Next click the browse button next to GDB Command file, to locate it you will need to Right-click to show hidden files to see it.  After you find it select it and click OK.


After entering the debugger and command file click Apply.
Now click Debug in the lower right hand corner of the Debug Configurations window to test the setup.  The first time you will get a confirmation window.


The Debugger will stop before the first line of the program.   Mouse over the icons to get descriptions of the debugger commands or use the Run menu.  See the Eclipse Help menu for more information on the Debug commands.
Debug-bbb_hello_world.png


F6 will step over so you can see the !!!Hello World!!! output in the Console window.
Debug hello world success.png


If this works you are finished setting up eclipse.  You should be able to debug your own programs using this setup as a guide.

If you need more help, a good reference is Michael Leonard’s article “Using Eclipse to Cross-Compile for the Beaglebone Black.”