5.3.2. Create a new board with EGOS

⚠️ WIP

5.3.2.1. Introduction

5.3.2.2. Naming convention

5.3.2.2.1. Build variables

The build system requires 3 specific variables to fetch the correct board and prepare compilation. These variables are:

  • TARGET_VENDOR: Name of the company (for example ERTOSGENER).
  • TARGET_NAME: Name of the board (for example EGOS_KIT_L476RG)
  • TARGET_VERSION: Version of the board. If board version is not needed, must be set to NONE in the build system

For the remaining of this document, examples will use the following values:

  • TARGET_VENDOR: ERTOSGENER
  • TARGET_NAME: EGOS_KIT_L476RG
  • TARGET_VERSION: NONE

5.3.2.2.2. Files and folder names

Unless state otherwise, all folder and file names, as well as C/C++ variable names, listed in this document SHALL be respected.

5.3.2.3. File architecture

5.3.2.3.1. _USER

The root folder for board specific files in the USER layer is 2_USER/SRC/inc/egos_cfg/BOARDS/<TARGET_VENDOR>/<TARGET_NAME>/{<TARGET_VERSION>/}, with TARGET_VENDOR and TARGET_NAME mandatory folders, and TARGET_VERSION optional.

This folder is organized as follows:

ERTOSGENER
|   EGOS_KIT_L476RG
|   |       egos_drv_cfg
|   |       |       egos_drv__cfg.h
|   |       |       egos_drv_com__cfg.h
|   |       |       egos_drv_com_at__cfg.h
|   |       |       egos_drv_com_lpwan__cfg.h
|   |       |       egos_drv_com_lpwan_lora__cfg.h
|   |       |       egos_drv_com_lpwan_sigfox__cfg.h
|   |       |       egos_drv_com_lrwpan__cfg.h
|   |       |       egos_drv_com_lwan__cfg.h
|   |       |       egos_drv_com_lwan_ble__cfg.h
|   |       |       egos_drv_com_nfc__cfg.h
|   |       |       egos_drv_com_wwan__cfg.h
|   |       |       egos_drv_hmi__cfg.h
|   |       |       egos_drv_hmi_button__cfg.h
|   |       |       egos_drv_hmi_console__cfg.h
|   |       |       egos_drv_hmi_glcd__cfg.h
|   |       |       egos_drv_hmi_led__cfg.h
|   |       |       egos_drv_imu__cfg.h
|   |       |       egos_drv_imu_acc__cfg.h
|   |       |       egos_drv_imu_gyr__cfg.h
|   |       |       egos_drv_imu_mag__cfg.h
|   |       |       egos_drv_imu_tmp__cfg.h
|   |       |       egos_drv_mem__cfg.h
|   |       |       egos_drv_mem_eeprom__cfg.h
|   |       |       egos_drv_mem_flash__cfg.h
|   |       |       egos_drv_mem_flash_manager__cfg.h
|   |       |       egos_drv_pos__cfg.h
|   |       |       egos_drv_pos_gnss__cfg.h
|   |       egos_hal_def
|   |       |       egos_hal__cfg.h
|   |       |       egos_hal_com__def.h
|   |       |       egos_hal_grp__def.h
|   |       |       egos_hal_irq__def.h
|   |       |       egos_hal_pin__def.h
|   |       |       egos_hal_pwr__def.h
|   |       |       egos_hal_rtc__cfg.h
|   |       |       egos_hal_rtc__def.h
|   |       egos_mdw_cfg
|   |       |       egos_mdw__cfg.h
|   |       egos_kernel_cfg
|   |       |       egos__cfg.h
|   |       |       egos_oss_dbg__cfg.h
|   |       |       egos_oss_exe__cfg.h
|   |       |       egos_oss_msg__cfg.h
|   |       |       egos_utl__cfg.h
|   |       |       egos_utl_chr__cfg.h
|   |       |       egos_utl_mem__cfg.h
|   |       |       egos_utl_mem_hash__cfg.h
|   |       |       egos_utl_num__cfg.h
|   |       |       egos_utl_num_math__cfg.h
|   |       |       egos_utl_num_type__cfg.h
|   |       |       egos_utl_str__cfg.h
|   |       |       egos_utl_tim_date__cfg.h
|   |       lib
|   |       linker
|   |       |       STM32L476RG_EGOS_512-512.ld
|   |       make_option
|   |       |       make_compiler_options
|   |       |       make_linker_options
|   |       |       make_MCU_BOARD_config

5.3.2.3.1.1. Folder egos_drv_cfg

This folder contains the driver configuration files. Theses files are used to indicate which driver are enabled on the board.

The presence of most of the configuration files is dependent on the configuration set for the layer above it. For example it is not needed to have a egos_drv_com_lwan_ble__cfg.h file if no BLE is available on the board (a BLE device is present if there is a dEGOS_DRV_COM_LWAN__CFG__USE_BLE defined in egos_drv_com_lwan__cfg.h).

In these configuration files must also be present the name of each processes enabled at each level.

For example, if the device uses any communication means (such as Lora), it must activate the dEGOS_DRV__CFG__USE_COM define in /2_USER/SRC/inc/egos_cfg/BOARDS/\/\/egos_drv_cfg/egos_drv__cfg.h and set the name for the drv_com process with the define cDRV_COM__PROC. Note that this name shall reflect the process tree.

It is important to note that modifying these headers without access to the BSPC source code SHALL be avoided, as this will result in a faulty application and can potentially damage the device.

5.3.2.3.1.2. Folder egos_hal_def

This folder contains high-level hardware information and configuration about the board.

For more information on how to fill these files, please refer to this section

5.3.2.3.1.3. Folder egos_mdw_cfg

This folder contains the configuration for the Middleware.

It is important to note that modifying these headers without access to the BSPC source code SHALL be avoided, as this will result in a faulty application and can potentially damage the device.

5.3.2.3.1.4. Folder egos_kernel_cfg

This folder contains the configuration for the Kernel

It is important to note that modifying these headers without access to the BSPC and Kernel source code SHALL be avoided, as this will result in a faulty application and can potentially damage the device.

5.3.2.3.1.5. Folder lib

This folder contains the library containing Kernel + BSPC compiled sources, used to build the USER application

5.3.2.3.1.6. Folder linker

This folder contains the linker script used at the linker phase.

5.3.2.3.1.6.1. Folder make_option

This folder contains necessary files for the build system.

  • make_compiler_options.mak: This file contains all the flags that will be passed to the compiler
  • make_linker_options.mak: This file contains all the flags that will be passed to the linker
  • make_MCU_BOARD_config.mak: This file contains the name of the linker file and the board name used for log purposes. This file must contain the following variables : MCU_LINKER_FILE, BOARD

5.3.2.3.2. _BSPC

The root folder for board specific files in the USER layer is 1_BSPC/SRC/src/egos_cfg/BOARDS/<TARGET_VENDOR>/<TARGET_NAME>/{<TARGET_VERSION>/}, with TARGET_VENDOR and TARGET_NAME mandatory folders, and TARGET_VERSION optional.

This folder is organized as follows:

ERTOSGENER
|   EGOS_KIT_L476RG
|   |       board_specific
|   |       egos_drv_hal_link
|   |       |       egos_drv_hal_lnk.h
|   |       egos_hal_cfg
|   |       |       hal_ana__cfg.h
|   |       |       hal_com__cfg.h
|   |       |       hal_pcb__cfg.h
|   |       |       hal_wdg__cfg.h
|   |       egos_hal_impl
|   |       |       hal__impl_bsp.h
|   |       |       hal__impl_bsp_.c
|   |       |       hal__impl_bsp__dma.h
|   |       |       hal__impl_bsp_access.h
|   |       |       hal__impl_bsp__com.cxx
|   |       |       hal__impl_bsp__com.h
|   |       |       hal__impl_bsp__dma.cxx
|   |       |       hal__impl_bsp__pcb.cxx
|   |       |       hal__impl_bsp__pcb.h
|   |       |       hal__impl_bsp__pwr.cxx
|   |       |       hal__impl_bsp__pwr.h
|   |       egos_mcu_impl
|   |       |       mcu_dev_sys__impl_stm32l4__cfg.h
|   |       make_option
|   |       |       make_MCU_BOARD_config.mak
|   |       |       make_MCU_BOARD_specific.mak

5.3.2.3.2.1. Folder board_specific

This folder contains board specific headers and source files. The files in this folder must be included via the make_MCU_BOARD_specific.mak makefile. It is up to the board creator to decide the architecture and file names in this folder.

5.3.2.3.2.3. Folder egos_hal_cfg

hal_ana__cfg.h contains the configuration on which Analog components from the MCU should be compiled for this board

hal_com__cfg.h contains the configuration on which Communication components from the MCU should be compiled for this board

5.3.2.3.2.4. Folder egos_hal_impl

hal__impl_bsp.h contains the list of all the processes each driver layer must launch. These lists take form as enumeration, on for each layer.

This file SHALL contain at least the eHalImplBsp_DrvProcChildren enumeration, which lists all the children of the root driver process. This enumeration SHALL have eHAL_IMPL_BSP__DRV_PROC_CHILDREN as its last field.

Depending on board/project needs, it SHALL also include all the children list for all the driver hierarchy.

⚠️ The list of enumeration name is still in construction !

hal__impl_bsp_.c contains the arrays of pointers to processes that each driver layer must launch. These arrays SHALL be of the same size as defined in the enumeration in hal__impl_bsp.h

This file SHALL contain at least the g__apcsDrvProcChildren array (of type pcsOssExe_ApiProc), which lists all the children of the root driver process. This enumeration SHALL have eHAL_IMPL_BSP__DRV_PROC_CHILDREN as its last field.

Depending on board/project needs, it SHALL also include all the children arrays for all the driver hierarchy.

⚠️ The list of array names name is still in construction !

For more specific details on the other files, please refer to this section

5.3.2.3.2.5. Folder egos_mcu_impl

5.3.2.3.3. Folder make_option

make_MCU_BOARD_config.mak is used to describe the underlying MCU hardware. It is used to select the correct implementation files

. It must contain the following variables: MCU_VENDOR, ARCH_VENDOR, ARCH_FAMILY, ARCH_VARIANT, ARCH_SPECIFIC, MCU_FAMILY, MCU_VARIANT, MCU_DERIVATE.

make_MCU_BOARD_specific.mak contains board/project specific build instructions. If the application is simple enough, this file can be left empty. It is up to the board creator to indicate what this specific board/project requires.

It must contains the following variables :BSPC_egos_board_specific_SRC_PATH, BSPC_egos_board_specific_HEADER_PATH.