{"type":"doc","content":[{"type":"paragraph","content":[{"text":"This tutorial will guide users through debug and development of embedded applications using Vitis from the command line interface (CLI), rather than the graphical unser interface (GUI) offered by the Eclipse-based IDE, with the ultimate goal of applying this to the integration of Vitis with a 3rd party tool. Understanding how Vitis can be driven from the CLI aids in the use of both scripted flows flows, version control systems, and 3rd party exampels. This will be demonstrated through integration with Visual Studio Code to develop and debug embedded application.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This tutorial used the Vitis 2021.1 release and although there is nothing specific about that version which this tutorial requires it's recommended that you follow this tutorial with that same release before attempting to use other ones.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Integration with VS Code is done here for demonstration purposes only and is not covered by Xilinx technical support. For more information see ","type":"text"},{"text":"Embedded SW Support","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/A/pages/18841631"}}]},{"text":".","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Table of Contents","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"7"},"exclude":{"value":"Table of Contents"}},"macroMetadata":{"macroId":{"value":"3dcb16b8645798c1f742eac4325b38d3"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"3d6ec442-05bf-4851-93a6-9a5a7b142a73"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"1. Introduction","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition to offering normal development functions, like code editing and debug, the Vitis IDE also handles the generation of device support packages, like boot firmware and drivers, based on a supplied hardware description file (XSA). And although the Vitis IDE is not built upon a fully scripted backend (such as Vivado) most functions are made available through the XSCT (Xilinx Software Command-line Tool) utility. Consequently, we will leverage XSCT throughout this tutorial to accomplish tasks that are normally native to the Vitis IDE.","type":"text"}]},{"type":"paragraph","content":[{"text":"On the subject of debug, the Vitis IDE does rely completely on a scripted backend exposed through a sub-set of XSCT commands. For use-cases where only these debug commands are needed a separate XSDB (Xilinx System Debugger) utility can be used. This XSDB has a smaller footprint and can be installed as part of a minimal set of Xilinx lab tools. Given this benefit, it will be the utility of choice for the debugging portion of this tutorial.","type":"text"}]},{"type":"paragraph","content":[{"text":"It should be noted that when XSCT is used to manage/create projects from the CLI it generates metadata that matches the metadata that would be generated by the Vitis IDE. This way a project workspace can be interchanged equally between CLI and IDE use.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"2. Creating a Vitis Development Workspace","type":"text"}]},{"type":"paragraph","content":[{"text":"This section will go over creation of a Vitis project workspace including mandatory device support components and a couple example Hello World applications. All the mandatory components are bundled into a Platform Project, while applications are bundled under a System Project.","type":"text"}]},{"type":"paragraph","content":[{"text":"Initially XSCT will be relied on to generate and build all these projects at least once. But beyond that the application projects can be built independent of Vitis. The one-time build by XSCT is required because it also generates the Makefiles for the applications.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2.1 Initializing Vitis Projects","type":"text"}]},{"type":"paragraph","content":[{"text":"Here we will rely on XSCT to perform a fair bit of under-the-hood automation with respect to ingesting a hardware specification file (XSA) and producing design-specific output products. All projects will be placed into a workspace folder designated by the ","type":"text"},{"text":"WORKSPACE","type":"text","marks":[{"type":"code"}]},{"text":" variable while the hardware specification is assigned to ","type":"text"},{"text":"XSA","type":"text","marks":[{"type":"code"}]},{"text":". The XSCT commands that build up the initial projects are captured in the supplied Makefile under the ","type":"text"},{"text":"init","type":"text","marks":[{"type":"code"}]},{"text":" target as shown below.","type":"text"}]},{"type":"codeBlock","content":[{"text":"init:\n\txsct -eval \"setws $(ws); \\\n\t\tplatform create -name $(plat_name) -hw $(xsa); \\\n\t\tdomain create -name $(domain_name_apu) -os standalone -proc psu_cortexa53_0; \\\n\t\tdomain create -name $(domain_name_rpu) -os standalone -proc psu_cortexr5_0; \\\n\t\tapp create -name $(app_name_apu) -platform $(plat_name) -domain $(domain_name_apu) -sysproj $(sys_name) -template {Hello World}; \\\n\t\tapp create -name $(app_name_rpu) -platform $(plat_name) -domain $(domain_name_rpu) -sysproj $(sys_name) -template {Hello World}; \\\n\t\tplatform active $(plat_name); \\\n\t\tplatform generate; \\\n\t\tapp build $(app_name_apu); \\\n\t\tapp build $(app_name_rpu)\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Consequently the workspace can be created as shown below.","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ export WORKSPACE=\n$ export XSA=\n$ make init","type":"text"}]},{"type":"paragraph","content":[{"text":"And the resulting workspace should resemble that shown below.","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ ls -hl $WORKSPACE\ntotal 24K\ndrwxrwxr-x 5 shaun shaun 4.0K Aug 5 09:35 hello_world_a53\ndrwxrwxr-x 5 shaun shaun 4.0K Aug 5 09:35 hello_world_r5\n-rw-rw-r-- 1 shaun shaun 4.3K Aug 5 09:35 IDE.log\ndrwxrwxr-x 9 shaun shaun 4.0K Aug 5 09:33 zcu102_plat\ndrwxrwxr-x 2 shaun shaun 4.0K Aug 5 09:33 zcu102_sys\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2.2 Building Projects","type":"text"}]},{"type":"paragraph","content":[{"text":"After project initialization/creation makefiles will be located under a ","type":"text"},{"text":"Debug","type":"text","marks":[{"type":"code"}]},{"text":" directory. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ ls -hl $WORKSPACE/hello_*/Debug/makefile\n-rw-rw-r-- 1 shaun shaun 1.6K Aug 3 15:34 build/hello_world_a53/Debug/makefile\n-rw-rw-r-- 1 shaun shaun 1.6K Aug 3 15:34 build/hello_world_r5/Debug/makefile","type":"text"}]},{"type":"paragraph","content":[{"text":"Now the applications can be built and cleaned using these makefiles. This is captured by the tutorial makefile under the ","type":"text"},{"text":"build","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"clean","type":"text","marks":[{"type":"code"}]},{"text":" targets as shown below.","type":"text"}]},{"type":"codeBlock","content":[{"text":"build: $(WORKSPACE)/$(app_name_apu)/Debug/makefile\n\tmake -C $(WORKSPACE)/$(app_name_apu)/Debug all \n\tmake -C $(WORKSPACE)/$(app_name_rpu)/Debug all \n\nclean: $(WORKSPACE)/$(app_name_apu)/Debug/makefile\n\tmake -C $(WORKSPACE)/$(app_name_apu)/Debug clean\n\tmake -C $(WORKSPACE)/$(app_name_rpu)/Debug clean","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2.3 Building with VS Code","type":"text"}]},{"type":"paragraph","content":[{"text":"Now let's begin demonstrating how VS Code could be used as a development environment. For the sake of simplicity we will leverage the toolchains that are installed by Vitis. That is, VS Code will call upon the same toolchain that Vitis uses. Note, however, that nothing prevents you from using your own toolchain installations.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Vitis installed toolchains are made available by sourcing environment settings provided by Vitis. So these can, in-turn, be made available to VS Code by opening it in a terminal where this environment is already set. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ source /Vitis/2021.1/settings64.sh\n$ which aarch64-none-elf-gdb # just confirming that aarch64 gdb is available\n/Vitis/2021.1/gnu/aarch64/lin/aarch64-none/bin/aarch64-none-elf-gdb\n$ which armr5-none-eabi-gdb # just confirming that armr5 gdb is available\n/Vitis/2021.1/gnu/armr5/lin/gcc-arm-none-eabi/bin/armr5-none-eabi-gdb\n$ code --folder-uri $WORKSPACE","type":"text"}]},{"type":"paragraph","content":[{"text":"Above we also used the ","type":"text"},{"text":"folder-uri","type":"text","marks":[{"type":"code"}]},{"text":" flag to open the ","type":"text"},{"text":"WORKSPACE","type":"text","marks":[{"type":"code"}]},{"text":" folder directly, but you can accomplish the same by selecting ","type":"text"},{"text":"File > Open Folder...","type":"text","marks":[{"type":"strong"}]},{"text":" from within VS Code. With VS Code open to ","type":"text"},{"text":"WORKSPACE","type":"text","marks":[{"type":"code"}]},{"text":" the project folders and files should appear in the Explorer pane.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":325,"id":"f18ab8e3-4b7a-4080-a3dd-7291faee43aa","collection":"contentId-2173435938","type":"file","height":318}}]},{"type":"paragraph","content":[{"text":"Now we'll create tasks for building and cleaning the projects. Select ","type":"text"},{"text":"Terminal > Configure Tasks...","type":"text","marks":[{"type":"strong"}]},{"text":" followed by the drop-down \"","type":"text"},{"text":"Create tasks.json file from template","type":"text","marks":[{"type":"strong"}]},{"text":"\" option and then finally the \"","type":"text"},{"text":"Others","type":"text","marks":[{"type":"strong"}]},{"text":"\" option. This will create a ","type":"text"},{"text":".vscode","type":"text","marks":[{"type":"code"}]},{"text":" folder within the ","type":"text"},{"text":"WORKSPACE","type":"text","marks":[{"type":"code"}]},{"text":" and a ","type":"text"},{"text":"tasks.json","type":"text","marks":[{"type":"code"}]},{"text":" file within that new folder.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"The exact options to create a","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"tasks.json","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"file may vary by version of VS Code but the general idea is that you should create this file.","type":"text","marks":[{"type":"em"}]}]}]},{"type":"paragraph","content":[{"text":"The new JSON file will open in the editor with a simple \"echo\" task example. All we will do is add a couple tasks to call ","type":"text"},{"text":"make","type":"text","marks":[{"type":"code"}]},{"text":" to build and clean the A53 application project. You can enter these directly based on the completed example below or use the VS Code IntelliSense feature to add a new task entry template (e.g. place cursor after closing curly bracket of existing task, then add a comma followed by a carriage return to position cursor for a new task entry, then use to select a task template) and adjust as shown in the example.","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n // See \n // for the documentation about the tasks.json format\n \"version\": \"2.0.0\",\n \"tasks\": [\n {\n \"label\": \"echo\",\n \"type\": \"shell\",\n \"command\": \"echo Hello\"\n },\n {\n \"label\": \"build a53\",\n \"type\": \"shell\",\n \"command\": \"make\",\n \"args\": [\n \"-C\",\n \"hello_world_a53/Debug\",\n \"all\"\n ],\n \"group\": {\n \"kind\": \"build\",\n \"isDefault\": true\n },\n \"problemMatcher\": []\n },\n {\n \"label\": \"clean a53\",\n \"type\": \"shell\",\n \"command\": \"make\",\n \"args\": [\n \"-C\",\n \"hello_world_a53/Debug\",\n \"clean\"\n ],\n \"problemMatcher\": []\n } \n ]\n}","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"The","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"problemMatcher","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"property avoids a secondary prompt when running a task. Without it VS Code will ask how you want to process task output. The empty value instructs VS Code to do nothing with task output. Additionally, in the example above we've used the","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"group","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"property to assign the build task as the default build action. This just makes the task directly accessible through","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"Terminal > Run Build Task","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":".","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Once the ","type":"text"},{"text":"tasks.json","type":"text","marks":[{"type":"code"}]},{"text":" file is updated and saved try out the new tasks through ","type":"text"},{"text":"Terminal > Run Tasks...","type":"text","marks":[{"type":"strong"}]},{"text":". If you keep an eye on the corresponding ","type":"text"},{"text":"Debug","type":"text","marks":[{"type":"code"}]},{"text":" folder you should see a clean remove the ELF file while a build will regenerate it.","type":"text"}]},{"type":"paragraph","content":[{"text":"If everything is working as expected you can then go back to the tasks JSON file and add two more similar entries for the R5 application. An example of a completed file is available in the ","type":"text"},{"text":"src","type":"text","marks":[{"type":"code"}]},{"text":" directory of this repo.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"3. Debugging with GDB","type":"text"}]},{"type":"paragraph","content":[{"text":"This section will guide you through debugging with GDB, which is an alternative to debugging with the Targeted Communication Framework (TCF). It's worth noting that debugging with TCF (referred to as System Debugger with respect to Vitis) is generally preferred over GDB and, consequently, is the default method used by Vitis. This is because, among other things, TCF more gracefully handles multi-core debug. However, GDB tends to have better 3rd party support (such as with VS Code) so it will be the method of choice in this tutorial.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3.1 Acquiring Init Script","type":"text"}]},{"type":"paragraph","content":[{"text":"The Vitis IDE normally handles some device specific initialization that is required before debugging can start. Ultimately, the goal it to debug an application on a specific core (e.g. Cortex-R5) for which a GDB binary supporting that architecture should suffice. However, that core is located on a unique SoC (Zynq MPCore UltraScale+ in this case) and that SoC must be initialized in a very device-specific manner before the ARM core is ready for running/debugging an application.","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to make this work outside of the Vitis IDE we will borrow the init script used by the IDE. But to do this we first need to do a trial run within the IDE. So start by opening the Vitis IDE and pointing to the existing workspace folder. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ vitis -workspace $WORKSPACE","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"If opening the workspace with the Vitis IDE fails for whatever reason you can follow these steps: (1) Delete the ","type":"text","marks":[{"type":"em"}]},{"text":"$WORKSPACE/.metadata","type":"text","marks":[{"type":"code"}]},{"text":" folder. (2) Select ","type":"text"},{"text":"File > Import...","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" (3) Choose the \"","type":"text"},{"text":"Eclipse workspace","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"\" option from the dialogue. (4) Browse to ","type":"text"},{"text":"$WORKSPACE","type":"text","marks":[{"type":"code"}]},{"text":" folder and select all projects folders. (5) De-select the \"","type":"text"},{"text":"Copy project into workspace","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"\" option and click \"","type":"text"},{"text":"Finish","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"\".","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Once the Vitis IDE is open right-click on the hello_world_a53 project (expand the zcu102_sys project under the Explorer view to see the application projects) to bring up the context menu and then select ","type":"text"},{"text":"Debug As > 3 Launch Hardware (Single Application Debug (GDB))","type":"text","marks":[{"type":"strong"}]},{"text":". This should change the IDE to the Debug perspective and a default breakpoint should become visible in the code editor once the debugger is connected and running.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"If the first time attempting to run GDB from IDE fails (e.g. failing to connect to target) just try again. If the issue persists check that the board connection is good.","type":"text","marks":[{"type":"em"}]}]}]},{"type":"paragraph","content":[{"text":"At this point there are 3 views/tabs worth noting:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Vitis Log","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Debugger Console","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"XSCT Console","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The Vitis Log records all the background activity performed by the IDE and also captures and warnings and errors. The Debugger Console will capture output from GDB. And, finally, the XSCT Console will capture XSCT output that results from Vitis background activity.","type":"text"}]},{"type":"paragraph","content":[{"text":"The init script we're after should appear in the Vitis Log, conveniently enclosed by:","type":"text"}]},{"type":"codeBlock","content":[{"text":"INFO\t: ----------------XSDB Script----------------\n...\n----------------End of Script----------------","type":"text"}]},{"type":"paragraph","content":[{"text":"Capture everything between those two lines (represented by the ","type":"text"},{"text":"...","type":"text","marks":[{"type":"code"}]},{"text":" above) and paste it into a new file. We'll name that file ","type":"text"},{"text":"dbg_init_a53.tcl","type":"text","marks":[{"type":"code"}]},{"text":". Once the script is captured you can terminate the active debug session (Ctrl+F2).","type":"text"}]},{"type":"paragraph","content":[{"text":"Now repeat the process above for the hello_world_r5 application project. We'll name the file for that script ","type":"text"},{"text":"dbg_init_a53.tcl","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Once both scripts are captured the Vitis IDE can be closed. Examples of these scripts can be found in the ","type":"text"},{"text":"src","type":"text","marks":[{"type":"code"}]},{"text":" directory of this repo.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3.2 Debugging from CLI","type":"text"}]},{"type":"paragraph","content":[{"text":"To test debugging from the CLI we'll use 3 different terminal windows.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One to capture program serial output (UART)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A 2nd to run the TCL init script and host a gdbserver","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A 3rd to run gdb","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The 2nd terminal uses XSCT/XSDB to both initialize the board for debug and host a gdbserver connection. XSCT/XSDB actually calls upon a separate ","type":"text"},{"text":"hw_server","type":"text","marks":[{"type":"code"}]},{"text":" utility for this gdbserver hosting but by default it will terminate if XSCT is closed. To ensure that gdbserver remains available XSCT/XSDB must run the script and then remain open. This is accomplished with the ","type":"text"},{"text":"-interactive","type":"text","marks":[{"type":"code"}]},{"text":" flag.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"hw_server","type":"text","marks":[{"type":"code"}]},{"text":" is also available as a standalone utility and although we don't call upon it directly in this tutorial it's built-in documentation can be referenced for more information on the ports used to host gdbserver. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ hw_server -help\nUsage: agent [OPTION]...\nStart Target Communication Framework agent.\n-d run in daemon mode (output is sent to system logger)\n...\n -p base port number for Xilinx GDB server\ndefault is 3000, -p0 disables the ports\nthe server opens one port per target architecture:\n3000: ARM; 3001: ARM64; 3002: MicroBlaze; 3003: MicroBlaze64","type":"text"}]},{"type":"paragraph","content":[{"text":"We'll start by opening the UART connection to the board. Here we use minicom but, of course, this can be substituted with any software of choice.","type":"text"}]},{"type":"paragraph","content":[{"text":"Term 1:","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"$ minicom zcu102\nWelcome to minicom 2.7\n\nOPTIONS: I18n \nCompiled on Nov 15 2018, 20:18:47.\nPort /dev/ttyUSB0, 10:40:28\n\nPress CTRL-A Z for help on special keys","type":"text"}]},{"type":"paragraph","content":[{"text":"Now in a separate terminal start XSCT/XSDB with the debug init script. Although not shown below (substituted with ","type":"text"},{"text":"...","type":"text","marks":[{"type":"code"}]},{"text":"), this will result in a lot of output as the script is processed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Term 2:","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"$ xsdb -interactive dbg_init_a53.tcl\n...\nxsdb%\n","type":"text"}]},{"type":"paragraph","content":[{"text":"If the script succeeds at initializing the device confirmation will be seen on the UART in the form of output from the boot loader firmware.","type":"text"}]},{"type":"paragraph","content":[{"text":"Term 1 Continued:","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"...\nXilinx Zynq MP First Stage Boot Loader \nRelease 2021.1 Aug 3 2021 - 19:33:38 \nPMU-FW is not running, certain applications may not be supported.","type":"text"}]},{"type":"paragraph","content":[{"text":"At this point the device should be ready for debug and we can start gdb. The below example will also walk through setting a breakpoint after the first line printed by the example application. That first line should appear on the UART and then will be followed by the second line only once gdb is instructed to continue running. Note that is used to terminate the program after it runs to completion.","type":"text"}]},{"type":"paragraph","content":[{"text":"Term 3:","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"$ aarch64-none-elf-gdb\n(gdb) tar ext localhost:3001\nRemote debugging using localhost:3001\nwarning: No executable has been specified and target does not support\ndetermining executable automatically. Try using the \"file\" command.\n0x0000000000000000 in ?? ()\n(gdb) mon ps\n1: Cortex-A53 #0 (Hardware Breakpoint)\n(gdb) file build/hello_world_a53/Debug/hello_world_a53.elf\nA program is being debugged already.\nAre you sure you want to change the file? (y or n) y\nReading symbols from build/hello_world_a53/Debug/hello_world_a53.elf...\n(gdb) break helloworld.c:58\nBreakpoint 1 at 0xd10: file ../src/helloworld.c, line 58.\n(gdb) continue\nContinuing.\n\nBreakpoint 1, main () at ../src/helloworld.c:58\n58 print(\"Successfully ran Hello World application\");\n(gdb) continue\nContinuing.\n^C\n(gdb) detach\nDetaching from program: /media/shaun/workspace/vitis/no_vitis/build/hello_world_a53/Debug/hello_world_a53.elf, process 1\n[Inferior 1 (process 1) detached]\n(gdb) disconnect\nEnding remote debugging.\n(gdb) quit","type":"text"}]},{"type":"paragraph","content":[{"text":"The following additional output should appear on the UART when the program completes.","type":"text"}]},{"type":"paragraph","content":[{"text":"Term 1 Continued:","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"...\nHello World\nSuccessfully ran Hello World application","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3.3 Debugging with VS Code","type":"text"}]},{"type":"paragraph","content":[{"text":"We'll now complete this tutorial by demonstrating how debugging can be integrated into VS Code. Start by installing the \"Native Debug\" extension which will be used to support interactions with GDB. For example:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":727,"id":"d412d670-f706-447b-a1d0-22ca9c50ab8a","collection":"contentId-2173435938","type":"file","height":161}}]},{"type":"paragraph","content":[{"text":"Now, in manner similar to how tasks were created, we will create some run configurations. A separate ","type":"text"},{"text":"launch.json","type":"text","marks":[{"type":"code"}]},{"text":" file manages these run configurations so the first step is to create this file.","type":"text"}]},{"type":"paragraph","content":[{"text":"Select ","type":"text"},{"text":"Run > Add Configuration...","type":"text","marks":[{"type":"strong"}]},{"text":" then select ","type":"text"},{"text":"GDB","type":"text","marks":[{"type":"strong"}]},{"text":" from the drop-down. This should open a newly created ","type":"text"},{"text":"launch.json","type":"text","marks":[{"type":"code"}]},{"text":" file which is also placed under the ","type":"text"},{"text":".vscode","type":"text","marks":[{"type":"code"}]},{"text":" directory. VS Code should also change to the Run view; if not you can manually switch with ","type":"text"},{"text":"View > Run","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"From the Run view a drop-down should be available from which you can select ","type":"text"},{"text":"Add Configuration...","type":"text","marks":[{"type":"strong"}]},{"text":" (also available under the ","type":"text"},{"text":"Run","type":"text","marks":[{"type":"strong"}]},{"text":" menu).","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":350,"id":"ca77e502-67c1-4794-b99e-25a8f78eb2ed","collection":"contentId-2173435938","type":"file","height":261}}]},{"type":"paragraph","content":[{"text":"This will open an IntelliSense menu in the editor from which you can select \"","type":"text"},{"text":"GDB: Debug external embedded device","type":"text","marks":[{"type":"strong"}]},{"text":"\".","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":766,"id":"aab56b39-13d1-4e4e-b2d4-65872ad8e275","collection":"contentId-2173435938","type":"file","height":408}}]},{"type":"paragraph","content":[{"text":"A new configuration entry will be added to the JSON file which should be updated to match the example below. In particular, make the following changes:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add \"gdbpath\" property to point to corresponding version of gdb (otherwise native x86 gdb will be used)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Update \"target\" property such that gdb connection command uses the appropriate port on localhost (note that ","type":"text"},{"text":"extended-remote","type":"text","marks":[{"type":"code"}]},{"text":" is just the long form of the ","type":"text"},{"text":"tar ext","type":"text","marks":[{"type":"code"}]},{"text":" command we used from the CLI).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Modify \"autorun\" property to match what we did from the CLI after connecting GDB to the gdbserver (i.e. load symbols).","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"{\n // Use IntelliSense to learn about possible attributes.\n // Hover to view descriptions of existing attributes.\n // For more information, visit: \n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"type\": \"gdb\",\n \"request\": \"attach\",\n \"name\": \"Debug APU\",\n \"gdbpath\": \"aarch64-none-elf-gdb\",\n \"target\": \"extended-remote localhost:3001\",\n \"executable\": \"./hello_world_a53/Debug/hello_world_a53.elf\",\n \"cwd\": \"${workspaceRoot}\",\n \"autorun\": [\n \"monitor ps\",\n \"set confirm off\",\n \"file ./hello_world_a53/Debug/hello_world_a53.elf\"\n ]\n },\n {\n \"name\": \"Debug\",\n \"type\": \"gdb\",\n \"request\": \"launch\",\n \"target\": \"./bin/executable\",\n \"cwd\": \"${workspaceRoot}\",\n \"valuesFormatting\": \"parseText\"\n } \n ]\n}","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"The absolute path isn't necessary for the \"gdbpath\" property because we launched VS Code from a terminal with the Vitis environment already sourced.","type":"text","marks":[{"type":"em"}]}]}]},{"type":"paragraph","content":[{"text":"Now that we have a Run/Debug configuration there's just one last thing needed before we can take Debug for a spin. Another task will be needed to initialize the device prior to running debug.","type":"text"}]},{"type":"paragraph","content":[{"text":"Once again edit the ","type":"text"},{"text":"tasks.json","type":"text","marks":[{"type":"code"}]},{"text":" file. If it's no longer open you can select ","type":"text"},{"text":"Terminal > Configure Tasks...","type":"text","marks":[{"type":"strong"}]},{"text":" and choose an arbitrary task.","type":"text"}]},{"type":"paragraph","content":[{"text":"Add a new task entry (either manually or using IntelliSense ) and populate it as given below. Notice that the task is just implementing the same XSCT/XSDB call we used on the CLI.","type":"text"}]},{"type":"codeBlock","content":[{"text":" {\n \"label\": \"gdb APU init\",\n \"type\": \"shell\",\n \"command\": \"xsdb\",\n \"args\": [\n \"-interactive\",\n \"../dbg_init_a53.tcl\"\n ]\n },","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Again, for the same reason noted earlier, the absolute path to XSDB for the \"command\" property isn't necessary.","type":"text","marks":[{"type":"em"}]}]}]},{"type":"paragraph","content":[{"text":"Now we're ready for debug! Start by running the debug init task. You should be able to see the task running in the Terminal window with confirmation that it's complete when the terminal comes to rest at the XSCT/XSDB prompt (e.g. ","type":"text"},{"text":"xsdb%","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]},{"type":"paragraph","content":[{"text":"Unlike the Vitis IDE there will be no default breakpoint set. So a debug run would just run the application to completion unless a breakpoint is added.","type":"text"}]},{"type":"paragraph","content":[{"text":"Open the ","type":"text"},{"text":"$WORKSPACE/hello_world_a53/src/helloworld.c","type":"text","marks":[{"type":"code"}]},{"text":" file and add a breakpoint at the 2nd print function. This will allow one lines to print over UART before the program is stalled. Then the second line will print when you either step one line or continue execution with VS Code.","type":"text"}]},{"type":"paragraph","content":[{"text":"Try it out by selecting \"Debug APU\" from the Run drop-down and then pressing the green play button just next to it.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":362,"id":"1da5bc6f-dcc9-4558-80b9-6e0fa52588ec","collection":"contentId-2173435938","type":"file","height":240}}]},{"type":"paragraph","content":[{"text":"Before wrapping up this demonstration it's important to note that each time a debug session is completed/detached the XSDB terminal session should be terminated (a button with a trashcan icon is provided by VS Code to terminate a terminal). Attempting to restart a debug session through the VS Code run buttons alone will not work. To start a new debug session simply restart the \"gdb init\" task after terminating the previous one.","type":"text"}]},{"type":"paragraph","content":[{"text":"Also, in case it wasn't already obvious, take note of the default location of the JSON files. They fall under the $WORKSPACE directory so if you decide to purge this directory make sure you've saved these files somewhere first.","type":"text"}]},{"type":"paragraph","content":[{"text":"Below is a closing screenshot of VS Code in debug action!","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":1167,"id":"abf7488b-72bb-4dbb-941e-dacf9e3d7d00","collection":"contentId-2173435938","type":"file","height":816}}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"4. Conclusion","type":"text"}]},{"type":"paragraph","content":[{"text":"Although a full installation of Vitis is required to initialize a project workspace subsequent use of the workspace from the perspective of application development can be accomplished with a much smaller set of Xilinx tools. For example, if the required GNU toolchains are supplied by the host system then only XSDB is needed outside of standard Linux development tools. It's worth noted that XSDB can be installed as part of a free Vivado Lab Edition with a much smaller footprint than fully functional Vivado installs.","type":"text"}]},{"type":"paragraph","content":[{"text":"However, any changes to the hardware definition file (XSA) will require XSCT, and therefore a complete Vitis installation, to regenerate device support components. In fact, even changes to the configuration of these components is ideally done through XSCT in order to keep the workspace compatible for use with the Vitis IDE (e.g. direct modification of makefiles will not be picked up by the IDE). This is obviously not ideal but moving forward we should start to see decreased reliances on XSCT for HW/SW interactions. In fact, work towards a device-tree based hardware description interface is already a work in progress.","type":"text"}]}],"version":1}