.. index:: RISCV64-ELF Topics .. _RISCV64-ELF_Topics_and_Tutorial: ================================= RISC-V 64-Bit Topics and Tutorial ================================= This appendix describes topics relevant to GNAT for bareboard 64-bit RISC-V and also presents a tutorial on building, running, and debugging an Ada application on an embedded 64-bit RISC-V board. .. _RISCV64-ELF_Supported_Processors_and_Run-Time_Libraries: Supported Processors and Run-Time Libraries =========================================== GNAT for bareboard 64-bit RISC-V supports processors conforming to the RISC V 64-bit instruction set and provides both pre-built generic and processor specific runtimes. Generic core runtimes --------------------- Generic Light run-times are provided for the following RISC-V ISA and extensions: * RV64IMAC: light-rv64imac * RV64IMAFC: light-rv64imafc * RV64IMAFDC: light-rv64imafdc To use these generic runtimes you are required to provide your own microcontroller specific startup code and linker scripts. To help create these files you can use the Startup-gen tool as documented in :title:`Startup-gen User's Guide` These generic Light run-times do not provide Ada.Text_IO functionality. For compatibility with existing code, the Ada.Text_IO package provided has its subprograms stubbed out. Processor runtimes ------------------ Run-time support is provided for Spike, the RISC-V ISA Simulator, and the Microsemi PolarFire SoC Icicle Kit For the Spike simulator, the following run-time library is pre-built: * light-spike For the Microsemi PolarFire SoC, the following run-time libraries are pre-built: * light-polarfiresoc * light-tasking-polarfiresoc * embedded-polarfiresoc All pre-built run-time libraries include the necessary low-level hardware startup and initialization functionality required to run applications on the developer board. In many cases, the pre-built run-time libraries will run on other developer boards and processors if they share a similar configuration to these pre-built run-times. If your processor or board uses a different configuration, you can modify and rebuild the pre-built run-time to meet your needs, or if you wish to target a different processor within the supported families, you can retarget the run-time. The run-time libraries are largely independent of the underlying hardware, simplifying this process. .. _RISCV64-ELF_Getting_Started: Getting Started =============== Developing with GNAT for bareboard 64-bit RISC-V is similar to native GNAT development, with two important differences. First, when building for a bareboard target you need to specify both the target processor and the run-time library. This can be defined in a project file (either directly or via the project properties dialog in GNAT Studio) or on the command line. For details on how to specify the target and run-time library for your project, see :ref:`introduction`. For all supported 64-bit RISC-V boards, the target 'riscv64-elf' needs to be specified. For example, the following project file fragment shows both the target and the run-time library specified via their respective attributes. In this example, a 64-bit RISC-V target and the 'Zero Foot Print' Spike run-time library is specified: .. code-block:: gpr project Demo is ... for Runtime ("Ada") use "light-spike"; for Target use "riscv64-elf"; ... end Demo; The second difference is how programs are run and debugged. This is dependent on your setup and the tools you use. In many cases, GNAT Studio can be used to debug your program. See :ref:`Debugging` for details. .. _Getting_Started_Spike: Getting Started with GNATemulator --------------------------------- This guide describes how to set up, build, run, and debug an Ada application using GNATemulator with the light-spike run-time. Setup for both Windows and Linux hosts is covered. While this section focuses on GNATemulator, most of the steps contained within this section are independent of the application and the target hardware itself. To begin this setup, it is assumed that GNAT for bareboard 64-bit RISC-V has been installed and that the install :file:`bin` directory is in the PATH environment variable. Once installed, ensure that the installation bin directory (by default :file:`bin/usr/local/bin`) included in your PATH. .. _Creating_Project: Creating a new Project ---------------------- Launch GNAT Studio: :: $ gnatstudio If this is your first time running GNAT Studio, note that GNAT Studio will create a configuration directory and will alert you via a pop-up dialog box. Press 'OK' to close that box and continue. A 'Tip of the Day' dialog will appear. Press Close to dismiss it. When on the `Welcome` page, click on ``Create new project`` and select ``Simple Ada project``, and then click on ``Next``. Change `Location` and `Settings` appropriately and press ``Apply``. The project view is now displayed; it is then possible to edit project properties by right-clicking on project name in the `Project` tab, and selecting `Project->Properties`. The project properties are now displayed. Open the `Toolchains` tab, and make sure that the `riscv64-elf` toolchain is selected and that the Ada run-time is `light-spike`. Then click on ``Save``. You can now navigate the project tree and add your source code. .. _RISCV64-ELF_Building: Building -------- Within GNAT Studio, build the project using either the ``Build Main`` button on the toolbar, or the :file:`Build/Project->Build All` menu entry. In the latter case, if a pop-up window appears, press the ``Execute`` button in order to build with the default settings. As GNAT Studio builds the project, it will display the ``Messages`` view at the bottom of the GNAT Studio window to show information about the build. On a successful build, the ``Memory Usage`` view will graphically display the memory usage of the program, unless the preference is disabled. (See the preference Build Targets/Project/Build Main page, among others, containing the ``Display memory usage`` check-box.) .. _RISCV64-ELF_Running_The_Program: Running the Program ------------------- Within GNAT Studio, run your program on the emulator using the ``Run with Emulator`` toolbar button or the `Build/Emulator->Run with Emulator` menu entry. As the program executes, it will display its output, if any, in the `riscv64-elf-gnatemu` view. .. _RISCV64-ELF_Debugging_The_Program: Debugging the Program --------------------- In GNAT Studio, click on the ``Debug with Emulator`` button on the toolbar. This will start a GNAT Studio debug session and launch the necessary tools required to debug the program on the board from GNAT Studio. The emulator will be automatically launched. Debugging a program on the emulator through GNAT Studio is similar to debugging a native program: * The program can continue to the next breakpoint by pressing the ``Continue`` button on the toolbar or by using the :file:`Debug/Continue` menu item. * The program can be stepped through statements using the corresponding menu items in :file:`Debug` menu and buttons on the toolbar. * The program can be interrupted by pressing :file:`-\\`, or through the :file:`Debug/Interrupt` menu. * Breakpoints can be set via the ``Breakpoints`` view, by clicking on the line numbers in the source editor while the program is interrupted or by right-clicking on the desired line and selecting ``Set breakpoint on line ...`` from the ``Debug`` menu. * Variables can be queried from the ``Variables`` view or by hovering the mouse over a variable with the program interrupted. GNAT Studio also provides a ``Debugger Console`` view that allows shell access to the underlying GDB client that is debugging the program. The GDB commands that correspond to the above debugging tasks can be entered directly into the console if desired. The debugging session can be exited via the :file:`Debug/Terminate` menu or by issuing the :file:`quit` command in the ``Debugger Console``.