GRISP

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:

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):

[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"
}