Using the C Development Environment

Folders

\Devtools

Contains tools and applications needed to compile the project.

• \eclipse: Eclipse IDE used for editing and debugging.
• \GNUToolsARMEmbedded: Cross-compile toolchain.
• \openocd: JTAG Debugger application.

\Workspace

The Eclipse workspace.

• \screvle: Root of the Screvle code tree.
  • \build: Makefile and other build tools. Compiled binaries will show in a sub-directory.
  • \project: C code modules. See below for more details.
  • \tools: Linker script.

Code Structure and Build System

Modules

All code is structured in modules. Each module can have a src and/or export directory.

• \export: Contains header files (.h) with the public ("exported") API. Other modules can include these header files.
• \src: Contains code files (.c) with the implementation of the API.

Directory Tree Layout

• \filesystem: Contains files that are intended to be stored on the SD card of Screvle.
• \import: Contains modules that are "imported", e.g. open-source modules.
• \prod: Contains "products" (or "firmware") that can be build. These are modules like any other module, but stored in a separate directory for ease of use.
• \src: Contains all Screvle modules, divided into several sub-directories by convention.
  • \board: Modules specific to a board (i.e. PCB)
  • \generic: Generic modules
  • \interface: Modules that only have an export directory that defines an interface (which is implemented in another module). E.g. "uart".
  • \lua: All Lua related modules.
  • \platform: Modules specific to a platform (i.e. microcontroller (family)). E.g. "stm32f2".

Build System

The Screvle Development Environment implements an easy to use, Makefile-based build system. The modules used for each product (firmware) are defined in a file (usually called "components.mak"). Building is done using the following command (executed in the \build directory):

make -r COMPONENT_FILE=../project/prod/screvle/components.mak PLATFORM=screvle-mini-l4 TARGET=cortex-m4f all

We can see several configuration options:

• COMPONENT_FILE: The file containing the modules to be compiled/linked.
• PLATFORM (board): The platform for which to compile.
• TARGET: The architecture of the target to compile for, defaults to cortex-m4f when not specified, so can be omitted in most cases.

Compilation requires several command line tools (e.g. "grep"). To support this on windows, the msys shell is included in the Development Environment. See directory \devtools\msys.

The result of the compilation step is:

• .elf: ELF executable of the application. This is used for debugging.
• .bin: Binary executable of the application. This is flashed to Screvle.
• .map: Map file usable for debugging.

These files can be found in the directory build\<product>_<board> (e.g. "build\screvle_screvle-mini-l4") 

How to make/edit a component file, see below.

Using Eclipse

The easiest and quickest way to get started is by using the Eclipse IDE. Note though that the Screvle code or build system is in no way tied to Eclipse and can be used with any development environment or via the command line.

To start Eclipse, execute "eclipse.bat" in the root of the development environment directory tree.

Selecting which product/platform to compile

The Eclipse installation delivered by Screvle has a custom plugin to easily switch between different product (firmware) and platform (board) combinations. The plugin works by looking for files with extension .buildconfig in the /project/prod directory. This file is a text file which contains key/value pairs, one per line, in the format "<key>=<value>". The following keys can be defined

To select a new Build Configuration, go to menu "Screvle->Configure Build" and select a .buildconfig file.

Compiling with Eclipse

After starting Eclipse, choose "Project->Build Project" to compile the standard Screvle application. This might take a while the first time.

Debugging with Eclipse

This section describes how to debug applications using the C Development Environment. Debugging is done via the OpenOCD tool and an Olimex JTAG dongle. The components used are:

• https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/
• https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/

The picture below shows how to connect the Olimex USB Tiny-H JTAG interface to Screvle. Note that by default the flat cable is inserted differently in the JTAG dongle so you need to swap it 180 degrees (or you can also rotate the connection on Screvle of course).

Starting OpenOCD

Depending on your board, the following OpenOCD Options are shown:

Start the correct OpenOCD, e.g. "OpenOCD JTAG" by selecting the "External Tools" dropdown icon and clicking "OpenOCD JTAG". If all goes well you will see the following output in the Eclipse console:

Open On-Chip Debugger 0.9.0-dev-00181-g1ea25b8-dirty (2014-10-08-14:06)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.sourceforge.net/doc/doxygen/bugs.html
Error: session's transport is not selected.
Info : session transport was not selected, defaulting to JTAG
adapter speed: 1000 kHz
adapter_nsrst_delay: 100
jtag_ntrst_delay: 100
cortex_m reset_config sysresetreq
write_configblock
Info : clock speed 1000 kHz
Info : JTAG tap: stm32f4x.cpu tap/device found: 0x4ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x4)
Info : JTAG tap: stm32f4x.bs tap/device found: 0x06419041 (mfg: 0x020, part: 0x6419, ver: 0x0)
Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints

Starting the debugger

Start debugging by selecting the "Debug" dropdown icon and clicking "screvle". Eclipse will now switch to the Debug perspective.

Flashing new firmware

After building, new firmware can be flashed to Screvle via OpenOCD. Please start OpenOCD as described above. Next open a command shell (Windows->Run->"cmd") and telnet to OpenOCD:

>telnet localhost 4444

You will now see the OpenOCD prompt. To flash the new firmware, execute the following command (edit the path to the correct absolute path).

Depending on your buildconfiguration, the name and location of the .bin will differ. The location is:

build/<PRODUCT>_<BOARD>/<BOARD>.bin

Open On-Chip Debugger
> write_application d:/screvle/workspace/screvle/build/screvle_screvle-handheld/screvle-handheld.bin 0x08008000

The output should look as follows:

Resettings Device
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0800119c msp: 0x20000a08
Writing Application
auto erase enabled
device id = 0x10036419
flash size = 2048kbytes
wrote 622592 bytes from file d:/screvle/workspace/screvle/build/screvle-stm32f4-screvle/stm32f4-screvle.bin in 18.894081s (32.179 KiB/s)
Resetting Device
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0800119c msp: 0x20000a08
>

Components Files

The core of the Screvle build system is the Components file. This is read by the Makefile based build system and can contain the following variables:

The components file can include other components files via "include <path>". Note that this path is relative to the "/build" directory.

Typically, you only edit the MODULES and FILESYSTEM variables when starting from an existing components.mak file.

MODULES

You can add the path to a modules (see description above; contains "src" and "export" subdirectories) to the MODULES variable to include it in the build. E.g.:

MODULES += \
           src/board/mini-l4/configuration_sdio \
           src/board/mini-l4/hwinit_leds_stm32l4 \
           src/board/mini-l4/hwinit_buttons

The .h files in the "export" subdirectory of these 3 modules will be included in the include-path. The .c files in the "src" subdirectory of these 3 modules will be compiled.

Note that these modules are added to the variable using "+=". Just using "=" would overwrite the variable and all previously included modules would not be build.

FILESYSTEM

You can add files to the SD Card image of a build by adding directories to the FILESYSTEM variable.

FILESYSTEM += \
              filesystem/screvle/mini/luamain \
              filesystem/screvle/mini/settings \
              filesystem/screvle/drivers/rndis

The content of these 3 directories is added to the root of the SD Card image.

The content of the Filesystem is stored in build/<product>_<board>/filesystem or build/<product>_<board>/filesystem_<variant> if variable VARIANT is defined (see Components File).