2.4. Introduction to EGOS

2.4.1. Introduction

This page explains, basically, the main principles of EGOS so that you can understand how it works in order to easily be able to develop your application on top of it.

For a deeper understanding of EGOS principles, please refer to the EGOS Documentation section.

The EGOS structure is composed as follow:

Structure

Each of the area integrate some features:

  • The Kernel integrates the utility services (memory management, system, utilities)
  • The BSP is the hardware implementation (drivers, HAL, MCU)
  • The USER is the application implementation

When you have the BPSC access, you have:

  • the Kernel library in 1_BSPC/SRC/lib
  • the accesses to the Kernel services (bspc_xx.h) and the configuration (bspc_xx__cfg.h) of the Kernel library in 1_BSPC/SRC/inc
  • the accesses to the BSPC and the Kernel from the application (egos_xx.h) and their configurations (egos_xx__cfg.h) in 2_USER/SRC/inc/egos_cfg
  • the application code in the 2_USER/SRC/src

When you have the User access, you have:

  • the Kernel and BSPC library in 2_USER/SRC/inc/egos_cfg/BOARDS/board_name/lib
  • the accesses to the BSPC and the Kernel from the application (egos_xx.h) and their configurations (egos_xx__cfg.h) in 2_USER/SRC/inc/egos_cfg
  • the application code in the 2_USER/SRC/src

In all the cases when the access contains a library, you do not have to change its configuration in order to stay relevant with the library.

By default the file ended with _.c are not compiled. They shall be included by another one.

The name of the files, variables, macros and so on give a hint to find its declaration.

Example: the sDrvHmi_Button_Chest structure is done in 1_BSPC/SRC/src/egos_drv/drv_hmi_button.h.

2.4.2. Main Principles

2.4.2.1. Processes

Egos is composed of processes. The goals of processes is to the separate the available memory and to share the running time. A process can not have a direct access to another process memory: each of them has its own stack. These processes can share data, event, allocate some memory or be managed by another one. To do this, a process identifier is used which is called the process handle. This handle can be retrieved by another process by its name. Each Egos process name is defined in the user file of the driver (i.e. 2_USER/SRC/inc folder). By example the name of the drv driver is defined in the 2_USER/SRC/inc/egos_drv/egos_drv.h by cDRV__PROC. When the name of the process to find is known, the mOSS_EXE__FIND.

Example: Find the driver process handle

handle hDrv
=   mOSS_EXE__FIND
    ( cDRV__PROC
    );

2.4.2.2. IPC

EGOS does not use global variables, principally in order to disable the access to an unvalid data when multiple processes are writing at the same address at the same time. In order to avoid that and to do some synchronization or to share some data, the processes use messages. The sender sends the message to a specific process by using the receiver handle.

2.4.2.3. APIs

EGOS is built at least with the Kernel library. At the user area the library fonctions are reachable by using the API functions. These ones are called with This->Api->... in a process: it is called the API tree. To simplify this kind of access to the user, the user APIs are called with a macro which name is prefixed by egos_...

#define egos_api1_subApi1(...)                                                                                 \
                    This->Api->Api1->SubApi1                                                                   \
                    (                                                                                                               \
                    )

The available APIs are defined in the public of the concerned module in 2_USER/SRC/inc.

2.4.2.4. Structure and APIs

EGOS is based on the use of C macros. It is done in the way to simplify the user development who just needs to call the relevant macro instead of creating a structure. The EGOS structures use the C++ definition in order to have initialized fields when the structure is instanciated.

DECL_TYPEDEF(struct, sTemplateStruct_1)
{ nU16                              nField1         =       1                                       // Note the default value
; nU16                              nField2         =       2                                       // Note the default value
;}  DECL_INSTANCE(struct, sTemplateStruct_1);

In order to be used in input parameter of the APIs, the following macro is used.

#define mTEMPLATE_STRUCT_1(...)                                                                                     \
                    DECL_COMPOSE                                                                                            \
                    ( sTemplateStruct_1                                                                                     \
                    , DECL_COMPOSE__INIT_NONE                                                                       \
                    , ## __VA_ARGS__                                                                                        \
                    )

It enables to create a local variable each time that a function needs to use this kind of structure. Then, only the needed fields shall be customized, the other fields have its default value. EGOS uses it in these APIs as follow (i.e. EGOS APIs are prefixed by egos_...).

#define egos_my_function(...)                                                           \
            my_function                                                                               \
            ( mTEMPLATE_STRUCT_1( __VA_ARGS__ )                                     \
            )

To personnalize the value of the fields, the points need to be replace by the field and its value when it is called.

egos_my_function(.nField2 = 5);

When egos_my_function is called like that, my_function is called with the default first field and the customized second field values.

2.4.3. Starting point of EGOS application

2.4.3.1. Main process

The entry point of EGOS is the mcu__impl_YOUR_.c file (by example mcu__impl_stm32l4_.c, this kind of file is in the EGOS private part) which contains the memory mapping, the bootloader and the reset handler which boots the OS.

The boot part of EGOS looks for the mAPP__MAIN function or one of its derivate in your application file (by example mAPP__MAIN_ADVANCED). The application files are located in the one of the subfolders of 2_USER/SRC/src/egos_app. For example this function is called in the egos_app/demo_try/demo_try__start_.c file which is an example to begin with EGOS. This function will create a process. The mAPP_MAIN is like the main function in a firmware application.

The difference between the the process create with the mAPP_MAIN macro (the "main" process), and a standard process is that the main process is created and launched automatically at boot.

This is how this function will look like:

mAPP__MAIN
( app_main_training__start                          ///< Application function
, (0)                                                                           ///< Size of private chest
, STR_OS("egos.app.P1")           ///< Application name
, STR_OS("1.0")                                                                       ///< Application version
)
{
    if
    (eOSS_EXE__STARTED__CREATION == mOSS_EXE__STARTED())
    // Application creation successful
    {
          // Add other lines
    }
    else
    // Application creation failed
    {
        // The current error number reflects the problem and might be returned
        mOSS_EXE__EXIT
        ( mOSS_EXE__ERROR()
        );
        // When you exit a process the "normal" way, the error code is returned
    }
    //Destruction of the process when it reaches this line
}

Then it is possible to create other processes or tasks from this main process to make a full application.

The compiled application is defined with the file name value of the MAIN constant definition.

2.4.3.2. Debug

To allow your software to print some message for debugging or doing a kind of human machine interface, mOSS_DBG_PRINT shall be used. It is going to print a message on the debug port if it is available wit a formalism: the first parameter is used to say which process printed and the second one is the display string.

The following call:

mOSS_DBG_PRINT("APP", "demo starts");

is going to print:

[APP] demo starts

The print with some variables can also be done as it is the case with the standard Lib-C with the printf call:

mOSS_DBG_PRINT("APP", "my var = %d", l_nMyvar);

The allocated memory per process can be printed: for example to know if there is a memory leak with a bad implementation:

egos_oss_dbg_StatsDisp( .i_nPeriod = 30);           // Period in seconds to display it periodically

All the debug messages may not be enable in EGOS, it shall be enabled by defining dDEBUG_XX. It can be useful to debug or to understand a behaviour of an application with a driver for example.

2.4.3.3. Coding rules

The EGOS naming is conventionned. Follow the guide to understand how it is done. In order to understand the main principles of the EGOS coding rules, the parts shall be read:

2.4.3.4. FAQ

  • How to use an EGOS feature?
  • How to know the available APIs?
    • EGOS API reference
    • egos_X_Y_Z macros in the header files egos_X_Y.h in 2_USER/SRC/inc/egos_X/ example : egos_drv_hmi_button_EventsSubscribe() in egos_drv_hmi_button.h dans egos_drv/
    • if it is about a driver feature, the concerned page can add some useful information.
  • What is the configuration of my available library ?
    • Located in the header configuration file (2_USER/SRC/inc/egos_cfg/BOARDS/board_name/egos_drv_cfg) #define dEGOS_DRV_X__CFG__USE_Y uncommented line in the parent X cfg file (egos_drv_X__cfg.h) in 2_USER/SRC/inc/egos_drv/ example : #define dEGOS_DRV_HMI__CFG__USE_BUTTON in egos_drv_hmi__cfg.h
  • How to notify of a bug detection?
    • Open an issue on your GitLab, the developer team will be notify of it
  • How to be trained to used EGOS?
    • Fill a formuler on EGOS website to have information about the following training sessions