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.
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
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".
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.
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
|COMPONTENT_FILE||components.mak||Optional: Which component file to use.|
|PLATFORM||Mandatory: Which board to compile for.|
|VARIANT||Optional: Which build to make, this variable is usually only relevant for generating the filesytem (SD Card content)|
|FILESYSTEM_SKIP_NAMED_BIN||Optional, set to true to enable.|
When enabled, does not include <product>_<platform>_<version>.bin on root of filesystem.
|FILESYSTEM_SKIP_BIN||Optional, set to true to enable.|
When enabled, does not include firmware.bin on root of filesystem.
To select a new Build Configuration, go to menu "Screvle->Configure Build" and select a .buildconfig file.
Just editing the active .buildconfig file does not apply these new settings to the build. When selecting a .buildconfig file via "Screvle->Configure Build", the Eclipse build settings are configured based on this file, but the .buildconfig file is not used afterwards. So when editing the .buildconfig file, it is necessary to select it again via "Screvle->Configure Build" before the new settings apply.
Compiling with Eclipse
After starting Eclipse, choose "Project->Build Project" to compile the standard Screvle application. This might take a while the first time.
If the menu command "Build Project" is not enabled, make sure at least one file of the project is opened and active (i.e. click on it to give it focus).
When compiling the first time, the following error may occur:
devtools\msys\bin\make.exe: *** couldn't commit memory for cygwin heap, Win32 error 0
This is due to memory limitations of some of the tools that are used. Simply restart compilation and it will continue where it stopped. Subsequent compilations should no longer show this error as only the edited files are compiled.
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:
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).
OpenOCD supports a wide range of JTAG interfaces. Please check OpenOCD documentation on how to configure OpenOCD for the JTAG interface of your choice.
Depending on your board, the following OpenOCD Options are shown:
|OpenOCD SWD L4||Used for STM32L4 based boards (low power MCU).|
|OpenOCD SWD||Used for STM32F4 based boards with SWD interface.|
|OpenOCD JTAG||Used for STM32F4 based boards with JTAG interface.|
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
The STM32F4 used in Screvle supports both JTAG and SWD for debugging. Due to a bug in the silicon of the STM32F4 JTAG does not work is GPIO Port B pin4 is used. This pin is only used when the optional Wifi Module is installed. It is easy to modify the Olimex JTAG dongle so it can be used with SWD. To do this, the following patched need to be applied:
When using SWD, start "OpenOCD SWD" instead of "OpenOCD JTAG".
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:
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 >
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:
|PRODUCT||Name of the product|
|MODULES||List of modules (directories) to compile.|
|FILESYSTEM||List of directories to include on the root of the SD card.|
|LDSCRIPT||Location of the linker script to be used.|
|ENTRY||Name of the function that is called when the device boots|
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.
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 += \
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.
You can add files to the SD Card image of a build by adding directories to the FILESYSTEM variable.
FILESYSTEM += \
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).
The copies are executed the order that the directories are added to the FILESYSTEM variable. So you can overwrite default files by including the custom version later in the FILESYSTEM directory list.