Difference between revisions of "BELK-AN-009: Using Visual Studio Code for remote debugging"

From DAVE Developer's Wiki
Jump to: navigation, search
(Starting a debug session)
(3 intermediate revisions by the same user not shown)
Line 41: Line 41:
 
The target has to be configured to mount the root file system over NFS. Please refer to [https://wiki.dave.eu/index.php/BELK/BXELK_Quick_Start_Guide#Target_configuration_for_the_development_stage_.28net_nfs.29|this link] for more details.
 
The target has to be configured to mount the root file system over NFS. Please refer to [https://wiki.dave.eu/index.php/BELK/BXELK_Quick_Start_Guide#Target_configuration_for_the_development_stage_.28net_nfs.29|this link] for more details.
  
The example project associated with this application note should be located in this directory of the host machine: <code>/bora/rfs/belk-4.0.0/home/root/hello</code>. This directory is seen by the target machine as <code>/home/root/hello</code>.
+
The example project associated with this application note should be copied in this directory of the host machine: <code>/bora/rfs/belk-4.0.0/home/root/hello</code>. This directory is seen by the target machine as <code>/home/root/hello</code>.
  
 
Please note that you need to change the permissions of the directory <code>/bora/rfs/belk-4.0.0/home/root/hello</code> in order to allow the user <code>dvdk</code> to access it without any restrictions:
 
Please note that you need to change the permissions of the directory <code>/bora/rfs/belk-4.0.0/home/root/hello</code> in order to allow the user <code>dvdk</code> to access it without any restrictions:
Line 52: Line 52:
 
drwxr-xrwx 4 root root 4096 Jun 12 14:55 hello/
 
drwxr-xrwx 4 root root 4096 Jun 12 14:55 hello/
 
</pre>
 
</pre>
 +
 +
 +
After completing this step, you should see these files:
 +
[[File:BELK-AN-009-tree.png|center|thumb|600px|Files of the example project]]
  
 
==The example project==
 
==The example project==
Line 58: Line 62:
 
The example makes use of a simple <code>Makefile</code> for cross-building. This <code>Makefile</code> can be used either to build the application manually or to build it automatically as part of a VSCode-controlled debugging session.
 
The example makes use of a simple <code>Makefile</code> for cross-building. This <code>Makefile</code> can be used either to build the application manually or to build it automatically as part of a VSCode-controlled debugging session.
  
The following image shows the files that the VSCode workspace consists of.
+
The following image shows the files that the VSCode workspace consists of.[[File:BELK-AN-009-workspace.png|thumb|center|600px|VSCode workspace]]
 
 
 
 
[[File:BELK-AN-009-workspace.png|thumb|center|600px|VSCode workspace]]
 
  
  
Line 72: Line 73:
 
**This script is invoked by VSCode to
 
**This script is invoked by VSCode to
 
***Build the program for the embedded target
 
***Build the program for the embedded target
***Start a remote debug session.
+
***Kill the gdbserver instance running on the target
 
*<code>cross-build.sh</code>
 
*<code>cross-build.sh</code>
 
**This script is invoked in turn by <code>remote-debugging.sh</code>. The final command that triggers the actual building process is <code>make hello</code>, that is the same command used to build the program manually.
 
**This script is invoked in turn by <code>remote-debugging.sh</code>. The final command that triggers the actual building process is <code>make hello</code>, that is the same command used to build the program manually.
*<code>start-gdbserver.sh</code>
+
*<code>start-gdbserver-loop.sh</code>
**This script is invoked by <code>remote-debugging.sh</code> to start a <code>gdbserver</code> instance on the target.
+
**This script is invoked only once on the target side; it guarantees that there is always a running instance of the gdbserver on the target
 
*<code>.gdbinit</code>
 
*<code>.gdbinit</code>
 
**In includes initialization scripts that are run by <code>/home/dvdk/bora/sdk/belk-4.0.0/sysroots/x86_64-petalinux-linux/usr/bin/arm-xilinx-linux-gnueabi/arm-xilinx-linux-gnueabi-gdb</code> upon startup. For more details, please see [http://man7.org/linux/man-pages/man5/gdbinit.5.html this page].
 
**In includes initialization scripts that are run by <code>/home/dvdk/bora/sdk/belk-4.0.0/sysroots/x86_64-petalinux-linux/usr/bin/arm-xilinx-linux-gnueabi/arm-xilinx-linux-gnueabi-gdb</code> upon startup. For more details, please see [http://man7.org/linux/man-pages/man5/gdbinit.5.html this page].
Line 86: Line 87:
 
****This is used to cross build the application on the host machine and to debug it on the target machine
 
****This is used to cross build the application on the host machine and to debug it on the target machine
 
*<code>tasks.json</code>
 
*<code>tasks.json</code>
**In this file two tasks are defined:
+
**In this file, two tasks are defined:
 
***<code>native build</code>
 
***<code>native build</code>
 
****This is used to build the program for the host target. In this case, an explicit command is run (<code>gcc -g -o hello.x86 hello.c</code>)
 
****This is used to build the program for the host target. In this case, an explicit command is run (<code>gcc -g -o hello.x86 hello.c</code>)
 
***<code>build and start remote debugging</code>
 
***<code>build and start remote debugging</code>
 
****As stated before, this task invokes the <code>remote-debugging.sh</code> script.
 
****As stated before, this task invokes the <code>remote-debugging.sh</code> script.
 +
==Starting a debug session==
 +
In practice, once the target is up and running and the example project was copied onto the host machine as stated previously, follow these steps to start a cross-debugging session.
 +
*Open the VSCode workspace
 +
*Go to the ''Terminal'' panel and open an ssh connection to the target machine
 +
**Once logged, execute the <code>start-gdbserver-loop.sh</code> script as shown in the following image.
 +
  
  
==Starting a debug session==
 
In practice, once the target is up and running and the example project was copied onto the host machine, follow these steps to start a cross-debugging session:
 
*Open the VSCode workspace
 
 
*Select the <code>(gdb) Cross launch</code> configuration
 
*Select the <code>(gdb) Cross launch</code> configuration
 
*Click on the green ''Start Debugging'' or select the ''Debug->Start Debugging'' menu item. Alternatively, press F5. You should see something like the following picture. It is worth remembering that the scripts take care of killing any <code>gdbserver</code> instance running on the target before starting a new debugging session. This allows starting it with just one click.
 
*Click on the green ''Start Debugging'' or select the ''Debug->Start Debugging'' menu item. Alternatively, press F5. You should see something like the following picture. It is worth remembering that the scripts take care of killing any <code>gdbserver</code> instance running on the target before starting a new debugging session. This allows starting it with just one click.

Revision as of 08:48, 14 June 2019

Info Box
Bora5-small.jpg Applies to Bora
BORA Xpress.png Applies to BORA Xpress
Warning-icon.png This application note was validated against specific versions of the kit only. It may not work with other versions. Supported versions are listed in the History section. Warning-icon.png

History

Version Date BELK/BXELK version Notes
4.0.0/2.0.0 June 2019 4.0.0 / 2.0.0 First release

Introduction

Visual Studio Code (VSCode for short) is a powerful integrated development environment (IDE). In the last years, it has gotten growing popularity among software developers of any kind, thanks to its excellent flexibility. Numerous extensions, native git support, availability for all of the most common platforms are some of the features that have made it so successful.

Even though it was not designed for embedded software development specifically, it is so versatile that it can be used for this purpose as well. This application note shows, for instance, how to configure it in order to remotely debug an application running on the Bora/BoraX platform. As host machine, the Virtual Machine released along with the BELK/BXELK kit was used.

It assumed that the reader is familiar with BELK/BXELK kit and with VSCode.

Host configuration

The example here described allows compiling and debugging the application for the host machine too. For this reason, the procedure indicates to install the native gdb debugger as well.

In essence, the followings are the packages that have to be installed:

  • Visual Studio Code with these extensions
    • C/C++
    • Native Debug
  • sshpass (sudo apt install sshpass)
  • gdb (sudo apt install gdb).


The two required extensions

Target configuration

The target has to be configured to mount the root file system over NFS. Please refer to link for more details.

The example project associated with this application note should be copied in this directory of the host machine: /bora/rfs/belk-4.0.0/home/root/hello. This directory is seen by the target machine as /home/root/hello.

Please note that you need to change the permissions of the directory /bora/rfs/belk-4.0.0/home/root/hello in order to allow the user dvdk to access it without any restrictions:

dvdk@vagrant-ubuntu-trusty-64:~/bora/rfs/belk-4.0.0/home/root$ ll
total 16
drwxr-xr-x 3 root root 4096 Jun 12 16:27 ./
drwxr-xr-x 3 root root 4096 Jul 10  2017 ../
-rw------- 1 root root 1102 Jun 12 10:41 .bash_history
drwxr-xrwx 4 root root 4096 Jun 12 14:55 hello/


After completing this step, you should see these files:

Files of the example project

The example project

The example project is the umpteenth flavor of the world-famous "Hello, world!" program. Source code is available [ here] for download.

The example makes use of a simple Makefile for cross-building. This Makefile can be used either to build the application manually or to build it automatically as part of a VSCode-controlled debugging session.

The following image shows the files that the VSCode workspace consists of.
VSCode workspace


The most relevant are:

  • hello.c
    • The source file of the program
  • Makefile
    • This file allows building the program manually from the command line. It is also used by VSCode to build the program before starting a debug session.
  • remote-debugging.sh
    • This script is invoked by VSCode to
      • Build the program for the embedded target
      • Kill the gdbserver instance running on the target
  • cross-build.sh
    • This script is invoked in turn by remote-debugging.sh. The final command that triggers the actual building process is make hello, that is the same command used to build the program manually.
  • start-gdbserver-loop.sh
    • This script is invoked only once on the target side; it guarantees that there is always a running instance of the gdbserver on the target
  • .gdbinit
    • In includes initialization scripts that are run by /home/dvdk/bora/sdk/belk-4.0.0/sysroots/x86_64-petalinux-linux/usr/bin/arm-xilinx-linux-gnueabi/arm-xilinx-linux-gnueabi-gdb upon startup. For more details, please see this page.
  • launch.json
    • In this file two configurations are defined:
      • (gdb) Native launch
        • This is used to build and debug the application on the host machine
      • (gdb) Cross launch
        • This is used to cross build the application on the host machine and to debug it on the target machine
  • tasks.json
    • In this file, two tasks are defined:
      • native build
        • This is used to build the program for the host target. In this case, an explicit command is run (gcc -g -o hello.x86 hello.c)
      • build and start remote debugging
        • As stated before, this task invokes the remote-debugging.sh script.

Starting a debug session

In practice, once the target is up and running and the example project was copied onto the host machine as stated previously, follow these steps to start a cross-debugging session.

  • Open the VSCode workspace
  • Go to the Terminal panel and open an ssh connection to the target machine
    • Once logged, execute the start-gdbserver-loop.sh script as shown in the following image.


  • Select the (gdb) Cross launch configuration
  • Click on the green Start Debugging or select the Debug->Start Debugging menu item. Alternatively, press F5. You should see something like the following picture. It is worth remembering that the scripts take care of killing any gdbserver instance running on the target before starting a new debugging session. This allows starting it with just one click.


Cross debugging session


For the sake of completeness, the native debugging session is illustrated as well.


Native debugging session