# RTOS Integration

eXtremeDB/rt supports all major real-time operating systems (RTOS) and is designed to integrate with a wide range of real-time environments. Real-time applications typically execute under the control of an RTOS or require direct access to hardware resources such as interrupts, timers, and memory management. Each RTOS platform places restrictions on which operating system services can be used, and they differ in their scheduling policies and methods of time measurement. As a result, the eXtremeDB/rt kernel must adapt to the specific characteristics of the target RTOS and hardware platform.

Because of this close integration, kernel components such as the transaction scheduler, recovery algorithms, database access API, and other subsystems are designed to interface with the services provided by the underlying RTOS. The degree of adaptation depends on the platform, and developers should expect variations in configuration and build procedures across different environments.

# Distribution Package

To address these variations, each eXtremeDB/rt distribution package includes the following:

- Source code for the real-time database kernel — enabling customization and adaptation to the target RTOS.
- Sample applications — illustrating recommended usage patterns and providing reference implementations.
- Platform-specific tools — assisting with building, configuring, and deploying the database kernel on the intended hardware and operating system. This structure ensures that developers can evaluate the kernel in a reference environment, then adapt it as needed for their specific target system.

# Prerequisites

Before building the eXtremeDB/rt kernel and sample applications, ensure the following prerequisites are in place:

- Toolchain: A cross-compiler toolchain appropriate for the target RTOS and hardware platform (e.g., GCC for Linux, or vendor-specific toolchains for embedded RTOS such as FreeRTOS or INTEGRITY).
- Build System: make or a compatible build utility. Some environments may also support CMake or IDE-based builds (e.g., Eclipse, IAR, or vendor-specific IDEs).
- Libraries/Headers: Standard C runtime libraries and RTOS-specific header files and libraries must be installed and accessible to the build system.
- Host Environment: A Linux or Windows development host with sufficient memory and disk space to compile the kernel and run tests.
- Target Hardware/Simulator: Either the actual target hardware board or a simulator/emulator provided by the RTOS vendor for development and testing.

Optional but recommended:

- Debugger/Monitor Tools (e.g., gdb, JTAG probes, or vendor debugging tools) for runtime inspection.
- RTOS SDK or BSP (Board Support Package) matching the target board.

# Building eXtremeDB/rt Kernel and Sample Applications

This section describes the general process for building the eXtremeDB/rt kernel and sample applications. Examples are provided for Linux as the reference environment. Developers working with other host/target configurations should adapt the steps accordingly.

If your setup differs significantly from the provided examples, please contact McObject for guidance and assistance.

## Linux

eXtremeDB/rt can be built on Linux (Intel x86) with the following commands:

### Build Libraries

        $ make target

        # Build 32-bit
        $ make x64=off target

### Build Samples

        $ make samples

        # Build 32-bit
        $ make x64=off samples

## Zephyr OS

ExtremeDB/rt can be built for Zephyr OS v4.0.

In order to integrate the eXtremeDB/rt database kernel into an application and run the provided samples:

1. Download and set up the Zephyr OS development environment as per its official documentation.
2. Download the eXtremeDB/rt package for Zephyr OS.

3. Unzip the package into a directory (e.g., the user's home directory):

           $ cd ~
           $ unzip extremedb_rt_1.4_zephyr.zip
           $ ls
             ... eXtremeDB_rt ...

4. Navigate to the Zephyr Workspace Directory (default is `~/zephyrproject`):

       	$ cd zephyr-workspace

5. Install eXtremeDB/rt into the Zephyr Source Tree.

   While in the zephyr-workspace directory, run the following installation script:

            $ ~/eXtremeDB_rt/install-zephyr.sh .

   The script will create necessary symbolic links in `zephyr/include`, `zephyr/lib`, and `zephyr/samples` directories of the workspace and include needed references in `lib/CMakeList.txt` and `lib/Kconfig files.`

6. Generate database API files

   In order to run samples included into the eXtremeDB/rt package, the sample's database API files need to be generated before building the samples. Navigate to the root directory of the eXtremeDB/rt installation and run `compile-schemas-x32.sh` or `compile-schemas-x64.sh` scripts depending on the databus width of the target (32 bit in most cases).

           $ ~/eXtremeDB_rt/compile-schemas-x32.sh

   Or for 64-bit target use:

           $ ~/eXtremeDB_rt/compile-schemas-x64.sh

7. To verify the installation, build and run the sample application:

           $ cd zephyr-workspace/zephyr
           $ west build -p -b qemu_x86 -t run samples/eXtremeDB_rt/perf-conv

8. There are a number of examples of how to use eXtremeDB/rt features. The sample programs are located in zephyr-workspace`/zephyr/samples/eXtremeDB_rt` directory. Use the following line to compile/run them:

           $ cd zephyr-workspace/zephyr

           $ west build -p -b qemu_x86 -t run samples/eXtremeDB_rt/eXtremeDB-sample-directory

   The sample programs include necessary settings files ( prj.conf files).

9. To integrate eXtremeDB/rt into a Zephyr application, follow these steps:
   1. Run Zephyr's Configurator

              $ cd zephyr-workspace/zephyr
              $ west build -p -b qemu_x86 -t menuconfig application-directory

   2. Enable eXtremeDB/rt DBMS component

      - Navigate to "Additional libraries" in the menu.
      - Check the option `"[ ] eXtremeDB/RT DBMS support"` to enable eXtremeDB/rt.
      - Once enabled, an "eXtremeDB/RT DBMS support" submenu will appear. Configure eXtremeDB/rt settings as required for your application.
   3. Generate the database API files for the application out of the schema definition file:

              $ cd application sources directory
              $ eXtremeDB/rt installation root directory/host/bin/mcocomp -x32 -f application-database-schema.mco

This will produce the database API files into the application directory. The files need to be added to the corresponding CMakeLists.txt file. Note: use -x64 instead of -x32 for 64-bit targets such as x86_64, Aarch64, etc. The eXtremeDB/rt samples (samples/eXtremeDB_rt/*) include default prj.conf file configurations that can serve as a starting point for your application.

### 1. Install Environment

Follow the official Zephyr documentation.

###

## DEOS

For DDC-I DEOS, build using the OpenArbor IDE.

1. Extract the package into a directory outside of any OpenArbor workspace.
2. Create a new OpenArbor workspace and follow the OpenArbor user guide to add a DEOS platform project appropriate for the target. Make sure to update the platform-specific settings (e.g. lwip.config) if using an actual board instead of a simulator.
3. Copy the `eXtremeDB_rt/eXtremeDB` from the extracted package to the top level directory of your workspace.
4. Copy a sample from the `eXtremeDB_rt/samples`. Copy a sample from the eXtremeDB_rt/samples directory to the top level directory of the workspace. Multiple samples may be copied, but only one must be included in the target load at a time.
5. Add the selected sample to the DEOS platform project's list of dependencies to Include it in the target load.
6. Update the target load and observe output.

The samples contain prebuilt eXtremeDB/rt database schemas. If a schema is changed, it needs to be rebuilt using the mcocomp utility located in the host/bin subdirectory of the package, e.g.:

        mcocomp -x32 -p /path/to/sample/src /path/to/sample/schema.mco

The samples are designed to run on a wide variety of platforms. However, the performance of these platforms may differ significantly. It may be necessary to tweak the supplied PD XML files to achieve optimal performance in some cases.

## embOS

Build for embOS on Cortex-M using SEGGER Embedded Studio.

The embOS downloads are available from the SEGGER Website.

The samples database is using a 2MB memory segment; also, more memory is needed for OS and eXtremeDB/rt internal structures. For running samples, 3MB of memory is needed; the simulator is configured for 4MB.

## FreeRTOS (ESP32)

eXtremeDB/rt can be built on FreeRTOS using the ESP-IDF framework and its CMake-based build system.

Note: that eXtremeDB/rt should not be prebuilt prior to usage: it is intended to be imported as a component into the applications.

The samples are located in the eXtremeDB_rt/samples subdirectory. Each sample requires an external SPI memory chip for database storage (at least 4 MB of SPI RAM). The ESP32 WROVER KIT board is recommended for running the sample executables.

To run a sample on a target board, first launch the ESP-IDF build environment as described in the ESP-IDF "Get Started" guide.

Next, use the idf.py tool to build a sample and flash the binary:

        idf.py build
        idf.py -p SERIAL_PORT_NAME flash
        idf.py -p SERIAL_PORT_NAME monitor

## FreeRTOS (General)

eXtremeDB/rt can be built on FreeRTOS for POSIX/Linux Simulator, NXP's iMX8QXP, and other platforms.

In order to build the database kernel, the following settings should be used:

### Linux Simulator

- `TARGET_OS=FreeRTOS` defines target OS for the build system
- `MCO_FREERTOS_ROOT_DIR=`path defines path to the FreeRTOS source tree (the topmost directory)

Use the following command line to build the product core and the samples for FreeRTOS POSIX/Linux SIM:

        make TARGET_OS=FreeRTOS \
             MCO_FREERTOS_ROOT_DIR=/home/user/.../FreeRTOSv202111.00

### NXP i.MX8QXP

- `TARGET_OS=FreeRTOS` defines target OS for the build system
- `TARGET_ARCH=imx8qxp` declares target board for the build system.
- `NXP_SDK_MKE_MIMX8QX=`path defines the path to the SDK's root directory, implying the path to FreeRTOS's source code tree.
- `TARGET_PLATFORM=`toolchain defines the toolchain to use to build the kernel/applications, eg. "arm-none-eabi”.

Use the following command line to build the product core and the samples for NXP's iMX8QXP board:

        make TARGET_OS=FreeRTOS \
             TARGET_PLATFORM=arm-none-eabi \
             TARGET_ARCH=imx8qxp \
             NXP_SDK_MKE_MIMX8QX=/path/to/sdk

The eXtremeDB/rt build system for iMX8QXP produces flat images suitable for downloading and execution on the target and ELF-images good for debugging.

For other platforms, set:

- `TARGET_OSFreeRTOS` defines the target OS for the build system.
- `MCO_FREERTOS_ROOT_DIR=`path defines the path to the FreeRTOS source tree (the topmost directory).
- `MCO_FREERTOS_PORT_DIR=`path defines the path to the target board port files.
- `MCO_FREERTOS_PROJECT_DIR=`path defines the path to the project's configuration files (FreeRTOSConfig.h).
- `TARGET_PLATFORM=`toolchain> defines the toolchain to use to build the kernel/applications, eg. "arm-none-eabi”.

## Integrity (GHS)

Use Green Hills MULTI IDE to build for IntegrityOS.

1. Open the eXtremeDB project file from the root directory of the package. Use `default.gpj` for 32-bit (such as ARM) and `default-x64.gpj` (ex. aarch64) for 64-bit targets.
2. The package includes a 32-bit version of the pre-compiled database API for the samples. Use compile-schemas.sh and compile-schemas-x64.sh to switch to the 32/64-bit version, respectively.
3. Select your target board from the Multi/Project/Set target menu.
4. Pay attention to eXtremeDB/rt's control defines. Refer to the sample projects and manual for the instructions.
5. Compile eXtremeDB/rt libraries and the sample projects.

## LynxOS-178

eXtremeDB/rt can be built on LynxOS-178 for x86. In order to build the database runtime, the following settings should be used:

- `TARGET_OS_HINT=LynxOS` passing the target OS to the build system
- `MCO_ENABLE_DYNAMIC_BINARIES=` to skip building dynamic libraries

To build static eXtremeDB/rt libraries:

        make TARGET_OS_HINT=LynxOS MCO_ENABLE_DYNAMIC_BINARIES= target

To build samples (only in the Development mode due to API restrictions):

        make TARGET_OS_HINT=LynxOS

## Nucleus

eXtremeDB/rt can be built on Nucleus OS as follows.

The package includes samples which use previously generated RTOS projects. Note that in order to start the project in QEMU, the OS image should contain DTB, and the simplest way to embed it is to use the EMBEDDED option:

        nu.os.svcs.libfdt.dtb_addr_location=EMBEDDED

By default, Nucleus is configured with a main task stack size of 4096. This is not enough for samples which are using the main task to perform operations, f.e. timer, in particular for 64-bit-based AArch64 architecture. Having a stack size that is not enough leads to unpredictable behavior. For eXtremeDB/rt samples, we recommend increasing the stack size to 32K by setting the following parameter in the configuration file:

        nu.os.svcs.appinit.main_task_stack_size=32768

One can set these options on a prepared OS project by performing the following steps:

1. Locate the config file in the ./bsp/<platform>/config/ directory. For example, `basic_kernel.config`
2. Add the line above to that file
3. Reconfigure the RTOS project with the command: `make config`

To deploy a sample project:

1. Start Nucleus devshell according to Nucleus documentation.
2. Deploy the Nucleus RTOS instance according to Nucleus documentation.
3. `cd` to eXtremeDB samples
4. Create a copy of the sample(s):

    	make createprj DEST=path-to-sample RTOS=path-to-RTOS-project

5. `cd` to the created sample
6. `make`

## QNX 7.1

eXtremeDB/rt can be built on QNX 7.1 for x86. In order to build the database runtime, the following settings should be used:

- `TARGET_OS=QNX` passing the target OS to the build system
- `TARGET_ARCH=gcc_ntox86_64|gcc_ntoaarch64le|gcc_ntoarmv7le` defining the target architecture

To build eXtremeDB/rt libraries (x86_64):

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntox86_64 target

        # produce aarch64 binaries
        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoaarch64le target

        # produce armv7 binaries
    $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoarmv7le target

To build eXtremeDB/rt libraries (x86_64):

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntox86_64 MCO_DISABLE=host samples

        # produce aarch64 binaries
        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoaarch64le MCO_DISABLE=host samples

        # produce armv7 binaries
        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoarmv7le MCO_DISABLE=host samples

## QNX 8

In order to build the database runtime, the following settings should be used:

- `TARGET_OS=QNX` passing the target OS to the build system
- `TARGET_ARCH=gcc_ntoaarch64le_cxx|gcc_ntoaarch64le_gpp|gcc_ntox86_64|gcc_ntox86_64_gpp|gcc_ntoaarch64le|gcc_ntox86_64_cxx|gcc_ntoarmv7le` defining the target architecture

Note: QNX development environment should be initialized by the following command:

        $ . ~/qnx800/qnxsdp-env.sh

To build eXtremeDB/rt libraries:

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntox86_64 target

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoaarch64le target

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoarmv7le target

To build samples:

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntox86_64 samples

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoaarch64le samples

        $ make TARGET_OS=QNX TARGET_ARCH=gcc_ntoarmv7le samples

## ThreadX (STM32F769-DISC0)

1. Create a project in STM32CubeIDE targeting STM32F769-DISC0.
2. Disable FreeRTOS as Azure RTOS is planned to use.
3. Enable Software Pack STMicroelectronics.X-CUBE-AZRTOS-F7 -> RTOS ThreadX -> ThreadX / Core.
4. Enable "RTOS ThreadX" under Software Packs -> STMicroelectronics.X-CUBE-AZRTOS-F7 category.
5. Build project.
6. Add eXtremeDB to the project:
   - Copy directories eXtremeDB_rt/include and eXtremeDB_rt/target to the project.
   - target/sal/smp/mcotx.c
   - Remove sal/fsys
   - Remove sal/hollow
   - Remove target/misc/mcostrrt.c and target/misc/mcodirrt*
   - Remove crypt/mcocryptaes.c
   - Remove mcotread.c and mcotglck.c
7. If network is required for running statistics REST API :
   - nx_bsd.[hc] is required
   - Middlewares/ST/threadx/ports/cortex_m7/gnu/inc/port.h: change `#define TX_THREAD_EXTENSION_3` to `#define TX_THREAD_EXTENSION_3 int bsd_errno;`
   Otherwise, remove directory ExtremeDB_rt/target/sal/net from the project.
8. Sample application reference_app is located in ExtremeDB_rt/samples/reference_app. Copy sample files:
   - main.c -> reference_app.c
   - threadx/platform.c -> threadx/platform.c
   - config.h
   - schema.mco
9. Put calls to the sample main function threadx_main to the appropriate place in the autogenerated main.c.
10. Note that the sample uses dynamic memory allocation using heap, so:
    - configure hardware in device configuration tool to enable SDRAM chip
    - configure project to place heap to the SDRAM chip
11. Compile schema with a command:

             eXtremeDB_rt/host/bin/mcocomp -x32 schema.mco

    Files demodb.h and demodb.c will be generated. Refresh project in STMCubeIDE so that files appear in the project.
12. Build the project and run it on the board.

## ThreadX (Linux Simulator)

Sample projects are prepared to be run on ThreadX with Linux simulator. To build samples, specify the following environment variables:

        THREAD_OS=threadx
        MCO_THREADX_INCLUDE_DIR=/home/denis/build/threadx/common/inc   # Include directory for threadx
        MCO_THREADX_LIBRARY_DIR=/home/denis/build/threadx/ports/linux/gnu/example_build  # ThreadX libraries directory
        MCO_THREADX_PORT_INCLUDE_DIR=/home/denis/build/threadx/ports/linux/gnu/inc   # Linux port

ThreadX does not have any wall time reference and has no conversions from/to real world time in seconds. All operations are made in ticks. Functions sleep_msec and sleep_usec are taking arguments in ticks instead of milliseconds (microseconds). The actual time each timer-tick represents is application-specific.

Parameters for newly created threads are specified as constants in target/sal/smp/mcotx.c:

        #define MCO_TX_THREAD_PRIORITY  1
        #define MCO_TX_THREAD_PREEMPT_THRESHOLD  1
        #define MCO_TX_THREAD_TIME_SLICE 10

Feel free to adjust these parameters according to your application and hardware requirements. According to our measurements on a Linux simulator, one tick can take 200~500ms on the same hardware depending on many factors.

Note: ThreadX uses ticks, not real time.

## ThreadX on NXP IMXRT Series

### IMXRT1066:

In order to build eXtremeDB/rt, download and install the SDK for ARM from the NXP website. The following environment variables must be set:

        NXP_SDK_RT1166=SDK path, for example: /home/user/SDK_2_13_0_MIMXRT1166xxxxx
        TARGET_PLATFORM=the compiler, for example:  arm-none-eabi
        TARGET_OS=threadx
        TARGET_ARCH=rt1166

Example:

        NXP_SDK_RT1166=/home/x/SDK_2_13_0_MIMXRT1166xxxxx TARGET_PLATFORM=arm-none-eabi TARGET_OS=threadx TARGET_ARCH=rt1166 make

### IMXRT1160:

In order to build eXtremeDB/rt, download and install the SDK for ARM from the NXP website. The following environment variables must be set:

        NXP_SDK_RT1060=SDK path, for example: /home/user/SDK_2_12_1_EVK-MIMXRT1060
        TARGET_PLATFORM=the compiler, for example: arm-none-eabi
        TARGET_OS=threadx
        TARGET_ARCH=rt1060

Example:

        NXP_SDK_RT1060=/home/x/SDK_2_12_1_EVK-MIMXRT1060 TARGET_PLATFORM=arm-none-eabi TARGET_OS=threadx TARGET_ARCH=rt1060 make

## VxWorks

eXtremeDB/rt can be built for WindRiver VxWorks 7.0 (ARM64 imx8qxp target board).

In order to build the code:

1. Import eXtremeDB/rt project files into your project.
2. Import eXtremeDB/rt core and sample projects into your workspace and add your BSP to build/run the samples.
3. Pay attention to eXtremeDB/rt's control defines. Refer to the sample projects for insights.