2.3. Developing and Building EGOS

2.3.1. Introduction

This page will guide you through all the tools configuration steps to be able to work with EGOS.

Prerequisite: Please note that you shall first make sure that you have installed every tools listed in Development-environment-setup page.

EGOS Download instructions

Now that you have executed all the tools setup steps, you are ready to access your dedicated GitLab group and download EGOS environment. Once you are logged-in, please go the GitLab Groups page in order to quickly access to your groups and projects. This should look like this (with the name of your company instead of ERTOSGENER):

gitlab-public-groups-page

In your company-dedicated group, you will find your EGOS release to work with, in a dedicated group named EGOS-Release-x.x (Note that this group name will probably change in the near future). This group is composed of a single GitLab project: EGOS_Project:, which contains the source code and libraries needed to work with EGOS. It also includes a folder named "EGOS_Tools" which provides all the necessary tools to compile EGOS locally, so that you only have to clone this single project, and you don't need to install the compiler yourself.

In order to work with EGOS, you need to download EGOS_Project repository:

  • As a user, you can simply download the EGOS release you have access to by clicking on the Download button (see the green square in the screenshot below) and select your favorite compressed file format (zip, tar, tag.gz, tar.bz2): download-as-zip.png
  • As a contributor, it is highly recommended to user Git: In EGOS_Projects description you can find the appropriate command to execute in order to clone the complete repository AND its submodule: EGOS_Tools. The command looks like the following:
git clone --recursive git@gitlab.ertosgener.com:'your_company_group'/EGOS-Releases/EGOS-Release-x.y/EGOS_Project.git

The original SSH link is provided on the top right of EGOS_Projects page under the blue Clone icon: gitlab-public-clone-link.png

You can select SSH or HTTPS protocols, but SSH is recommended, although it requires that the TCP port 22 shall be open in your companys firewall.

2.3.2. EGOS Project file structure

Inside EGOS_Project repository you will find 3 folders:

  • 1_BSPC: contains the BSP (Board Support Package) source files so you can develop your own drivers, add specific HW board support as well as add new microcontroller support. These files are located under 1_BSPC\SRC\src. In 1_BSPC\SRC\inc are some BSPC-public header files which are not fully public but required for driver development.
  • 2_USER: contains the public APIs available for you as an application developer. These are located under 2_USER\SRC\inc. This folder also contains various application examples, so that you can easily adapt them or develop your own application. These files are located under 2_USER\SRC\src\egos_app.
  • EGOS_Tools: contains the required tools to build EGOS, mainly the compiler (GCC for ARM).

Further details about how to work and develop with EGOS will be provided during training sessions and also in the public documentation.

2.3.3. Eclipse CDT Workspace setup

2.1. Launch Eclipse CDT

2.2. Paste the 'your_project_path'/EGOS_Project/x_xxx/PRJ/Eclipse path (Careful not to select a folder inside /PRJ/Eclipse !) into the prompted window and click on "Launch": eclipse-workspace-setup-launch

2.3. Discard the Eclipse "Welcome" page. Hint: you can prevent this Welcome windows from opening all the time by unchecking the box "Always show Welcome at start up" on the bottom right: eclipse-welcome-screen

2.4. No Project should be available in your workspace: this is normal, we will now import it.

  1. On the Project Explorer panel on the left, click on "Import projects..." eclipse-import-project

  2. Select "General" then "Existing Projects into Workspace": eclipse-import-existing-project

  3. Click on "Browse" then select the only folder available: An Eclipse project will be detected so you can import it. eclipse-import-project

  4. Click on "Finish" to validate the import. You can now see the sources files of the project and the appropriate Makefile folder in the Project Explorer panel: eclipse-project-explorer

  5. On the right panel, click on "Build Targets" tab to get the available targets for building your projects: eclipse-build-targets

7.1. You can double click on the one you need to trigger the appropriate build action.

7.2. "Build All (no clean)" will build EGOS by compiling only the files which have been modified since your last build

7.3. "Clean & Build all" will clean everything and compile everything again.

7.4. "Clean all" will clean everything that was previously generated

Now your environment is setup and you can start developing with EGOS!

2.3.4. Build System Usage

2.3.4.1. Location

The build system is located in each source repository: 1_BSPC and 2_USER, under the sub-folder: .../PRJ/MAKEFILE. Depending on your role, you need to use the correct one:

  • If you are an application developer or user, then you only have access to 2_USER.
  • If you are a contributor, then it is recommended to use the makefiles located in 1_BSPC/PRJ/MAKEFILE folder: Indeed, using this folder will allow you to compile the complete BSPC layer as well as the application layer all together in one pass. You can of course use the User dedicated makefiles in 2_USER/PRJ/MAKEFILE but this will require the BSPC library to compile, which you will have to generate using 1_BSPC makefiles...

2.3.4.2. Usage

To use the build system, you need to:

  • Launch a shell (CMD.exe on Windows or bash/sh on Linux systems)
  • Change directory to EGOS_Project/1_BSPC/PRJ/MAKEFILE/ or EGOS_Project/2_USER/PRJ/MAKEFILE/
  • Run the "make all" command to build the complete project with the default application.

=> The object and binary files will be generated in a sub folder with the name corresponding to the target your built.

In order to get the list of supported 'make' target, simply type "make" or "make help".

If you want to build another application than the default one, you need to provide the source file name when calling 'make', using MAIN=my_demo_app_.c

  • Example: make all MAIN=my_demo_app_.c

2.3.4.2.1. Troubleshooting

It can happen that you encounter the following error on Windows computer:

D:/1133_EGOS_GROUP/EGOS_PROJECT/1_BSPC/PRJ/MAKEFILE> make all
Deleting *.o files...
process_begin: CreateProcess(NULL, del /Q /F D:/1133_EGOS_GROUP/EGOS_PROJECT/1_BSPC/PRJ/MAKEFILE/_EGOS_BSP_NUCLEO_L476RG_build*.o, ...) failed.
make (e=2): Le fichier spcifi est introuvable.
Makefile:456: recipe for target 'clean_all' failed
mingw32-make: *** [clean_all] Error 2

You can remark that the path is not interpreted correctly: D:/1133_EGOS_GROUP/EGOS_PROJECT/1_BSPC/PRJ/MAKEFILE/_EGOS_BSP_NUCLEO_L476RG_build*.o: there is a missing "//" before "*.o".

It's an issue related to slash and anti-slash depending on Windows or Linux system: the most probable reason is that the Git/bin folder is part of your PATH environment variable in your system and therefore bash shell commands are interpreted instead of Windows command shell only.

Please check your Windows environment variable and remove the path to your Git/bin (most probably: C:/Program Files (x86)/Git/bin) if present in the "Path" variable. You may need to restart your computer so that the changes are taken into account, although it seems that with Windows 10 it's not needed anymore, but you need to restart your CMD shell.

2.3.5. Debugging tools

As mentioned above, there are many tools which can be used for debugging purpose. One tool that is used internally at eRTOSgener is SEGGER Ozone, which can be combined with SEGGER SystemView for visualization of the scheduling.

Note: However, using these tools requires that you have a compatible SEGGER Probe

2.3.5.2. Visualizing SWO data in Eclipse

EGOS allows you to have debug output using either UART or SWO which is an ARM functionality (ARM Cortex-M Single Wire Output). Although UART is the most command way of debugging it is also very slow, which makes SWO very interesting.

You can visualize the SWO output using SEGGER Ozone or SEGGER J-Link SWO Viewer tool, available on SEGGER website. You can find a dedicated documentation to setup and use this tool here.

It is also possible to use Eclipse to visualize the SWO data, by following these steps:

In Eclipse, in your debug configuration settings, tab "Startup", you need to select "Enable SWO" and to configure the "CPU Freq" to your target's CPU frequency (24Mhz in the example below), and to select a SWO frequency which shall be a multiple of the CPU frequency, 2Mhz in the example below. The port mask can be 0x1 as it is by default :

image

And that's pretty much it!

To visualize your data, simply go to the console view:

image

2.3.5.3. SEGGER Ozone Project configuration

Ozone is a cross-platform debugger and performance analyzer for J-Link and J-Trace. Ozone is a full-featured graphical debugger for embedded applications. With Ozone it is possible to debug any embedded application on C/C++ source and assembly level. Ozone can load applications built with any tool chain / IDE or debug the target's resident application without any source. Ozone includes all well-known debug controls and information windows and makes use of the best performance of J-Link and J-Trace debug probes. The user interface is designed to be used intuitively and is fully configurable. All windows can be moved, re-sized and docked to fit the need of any developer.

In order to be able to debug your application with Ozone, please follow these steps:

  1. First you need to launch Ozone

  2. At startup, the following menu will appear. Select "Create New Project": ozone-config

  3. Then you need to select the target you are working on by scrolling to the correct derivate of your C: systemview-config

  4. On the next windows, you need to select "SWD" for the Target interface, and also "8 MHz" for the Target Interface Speed: systeview-config-3

5.Finally, you need to select the .elf file you want to load on your target: systemview-elf-import

From here you can debug your application like with any debugger tool.

NOTE: It is recommended to save your configuration file to your project's repository so you don't have to redo these steps every time.

SEGGER SystemView configuration

NOTE: SystemView is not mandatory to run and debug EGOS, it's a support tool which is dedicated to advanced user only.

SystemView is a real-time recording and visualization tool for embedded systems that reveals the true runtime behavior of an application, going far deeper than the system insights provided by debuggers. This is particularly effective when developing and working with complex embedded systems comprising multiple threads and interrupts: SystemView can ensure a system performs as designed, can track down inefficiencies, and show unintended interactions and resource conflicts, with a focus on the details of every single system tick

It can be used with Ozone easily.

  1. First you need to make sure that the J-Link Software and documentation package is already installed on your laptop. If it's not the cas, please read the dedicated section above.
  2. Once Ozone is started, you can launch SystemView.
  3. On the main screen, click on the green "play" button on top left. A small window appears, normally it should be configured correctly based on your Ozone project configuration:

    • Connection to J-Link shall be set to "USB"
    • Target Device shall be exactly the same than the one you selected on Ozone
    • Target Interface & Speed shall be configured to "SWD" and "8000" KHz
    • RTT Control Block Detection shall be set to "Auto Detection" systemview-config
  4. Before continuing, you need to start your code execution with Ozone debugger so that SystemView records exactly what you want/need.

  5. Then you can click on "OK" on SystemView and record the data. NOTE that you are limited to 1 million events with the free version of SystemView.
  6. Don't forget to click on the "Stop" button to stop the recording.

Troubleshooting

If you encounter problems connecting to you On Board Jlink, follow this link : https://wiki.segger.com/J-Link_cannot_connect_to_the_CPU

Here are the option you need to choose :

JLinkconnect

While using Eclipse to debug, you may encounter this error : debugPrjPathErr

This is because the path variable ${project_loc} is local to the current active tab. You have to make sure that the active tab is the project tab and not the debug tab when starting debugging. When the debugger has started, you are free to switch between tabs at will.

The following tab selection will trigger this error : debugPrjPathKO

This tab selection will not trigger this error : debugPrjPathOk