GRISP

:toc: == Prerequisites

• the +xz+ decompression tool needs to be installed

• the +zlib+ development files are necessary

• +bison+, +flex+ and +texinfo+

• to check for some of RTEMS source builders prerequisites

  git submodule init git submodule update rtems-source-builder cd rtems-source-builder ./source-builder/sb-check

== Quick Start Guide

You can build the whole toolchain by running +./build/build.sh+. See <<Building>> for more details.

To build the simple RTEMS sample application, go to +grisp-simple-sample+ and call +make+.

If you want to use OpenOCD, you have to make sure that you have read and write access to the USB device. On a Linux system using udev, you can copy the udev-rule from build/99-grisp.rule to /etc/udev/rules.d/ for that. The rule also provides a fixed name for the serial console (/dev/ttyGRiSP).

== Directory Structure

The following directory structure is used in this project:

• build: scripts for building the tool chain and libraries
• grisp-XYZ: applications
• libXYZ: non-RTEMS libraries
• rtems-XYZ: software and libraries related to RTEMS
• README.asciidoc: this document

== Building

The complete toolchain is built by running +./build/build.sh+. This will do the following:

• check out the necessary git submodules
• bootstrap RTEMS
• build and install the toolchain
• build and install the RTEMS BSP
• build and install necessary libs

All installations are made inside the +rtems-install+ subdirectory in the base directory of the repository. To change the install location edit the +PREFIX+ in +build/configuration.sh+.

== git Repository Structure

The +grisp-software+ project pulls in a number of git submodules (like RTEMS). Most of these submodules have been forked with no or only minimal changes. The branches in the submodules follow the following guidelines:

• +master+ tracks the upstream development of the project.
• If patches are necessary, they will be added on branches and the commits on the branch are referenced in +grisp-software+.

Here is an example for how a git tree of a submodule could look like:

o---o---o---B'--o---o---o---o---o---o master (clone of upstream/master) \
\ A'--C' grisp-20171110-xyz
A---B---C grisp-20171020-xyz

In that example +grisp-20171020-xyz+ is a version of the software with some adaptions for GRiSP. If for example a (maybe slightly modified) version of the patch +B+ has been accepted in the upstream repository and GRiSP now wants to update to a newer version of the master, +B+ is no longer necessary. Therefore the new +grisp-20171110-xyx+ no longer contains +B+ but (adapted) versions of +A+ and +C+ are still necessary.

The old +grisp-20171020-xyz+ is still be kept so that a old version of the +grisp-software+ repository can still access the commits.

That structure makes it relatively easy to see the exact differences to the upstream version and which patches might should be integrated into it in the future. The disadvantage is that it will leave quite a number of old branches that are still necessary so that older +grisp-software+ revisions can reference them.

=== Re-Building only target specific RTEMS libs

Since building the toolchain takes a lot of time and since the toolchain changes less often than the rest of the system you can also just rebuild RTEMS and its libs.

To do that delete the rtems-install/rtems-4.12/arm-rtems4.12/atsamv directory and then do a

./build/build.sh --no-toolchain --no-bootstrap

=== Updating the submodules from github

When you want to rebuild with some new version from the Git repos you need to make sure that you update the sumodules:

git pull git submodule update

=== Cleaning

Normally, running ./build/build.sh (or any other of the individual build scripts in the ./build folder) should rebuild without the need for cleaning.

However, if you want a clean start you can delete the rtems-install folder which will delete all created binaries, libraries and header files.

To make a complete reset of the whole repository, use the following commands:

[source,shell]

git co . # Reverts all uncommited changes git clean -dxn # gives a preview, what unversioned files would be deleted git clean -dxf # deletes everything that is not under version control

== Boot Loader

The boot loader will try to initialize and mount the SD card. In case this is successful it tries to read the +grisp.ini+ configuration file from the SD root directory.

Sample grisp.ini (showing the default values): [source,ini]

[boot] timeout_in_seconds = 3 image_path = /media/mmcsd-0-0/grisp.bin

All values are optional and in case something is missing default values will be used (presented in the listing above). Once the timeout expired without user input the automatic application load sequence starts.

=== Updating the Boot Loader

For updating the bootloader build OpenOCD by running ./build/build-openocd.sh. You can then update the boot loader with the following call:

./build/debug-load-flash.sh grisp-bootloader/binaries/bootloader.exe

The process will need quite some time (about 30 seconds for loading and about a minute for verify).

If OpenOCD is failing due to libusb related issues, you might need to make adjustments specific to your operating system. Please see the libusb FAQ: https://github.com/libusb/libusb/wiki/FAQ

== Debugging

It is possible to debug an application using the on-board FTDI to SWD adapter. First build and install OpenOCD by running ./build/build-openocd.sh.

Place a SD with some sample application into the target. This takes care that the bootloader starts an application. The debug scripts will wait for this and then overwrite the application that is booted by the bootloader with the one that should be debugged.

After that you should start openocd on one console using ./build/debug-start-openocd.sh. This starts an GDB-Server. Do not terminate the process. You can then start a gdb that connects to the server using ./build/debug-start-gdb.sh path/to/app.exe. The script adds a reset command to the normal gdb that restarts the target and reloads the application. Note that for bigger applications, that might need quite some time.

== WiFi

By default, the wpa_supplicant.conf from the root of the SD card will be used. For a default WPA2 encrypted network, the file should look like follows:

network={ ssid="mynetwork" key_mgmt=WPA-PSK psk="secret" }