#####################
Self-realtimeness
#####################

.. contents::
  :local:
  :depth: 1

Introduction
============

Features
========

Place in architecture
=====================

User guide
==========
Option 1
--------
To use the NLC, build its Docker image with the following command:
    
    docker build . -t nlc:latest

Then push the image to a local registry (at localhost:5000):

    docker tag nlc:latest localhost:5000/nlc:latest
    docker push localhost:5000/nlc:latest

Copy the `docker-compose.yml` file to the node. Additionally, copy the `config.json` file to `/etc/aeros/self-realtimeness/`
on the host. Then run 

    docker compose up

to start the NLC.

Option 2
--------
Clone the repo directly on the node and execute the build command from above. This way no registry is required, but the image field in the `docker-compose.yml` 
file needs to be adapted. The `config.json` file still needs to be copied to `/etc/aeros/self-realtimeness/`.

Prerequisities
==============

Installation
============

Configuration options
=====================
* `kernel_module_name: str`: The path to the KM object file (`.ko`).
* `interval_tu: str`: The mode for the frequency of the TU calculations. Can be one of the following: `"min", "medium", "max"`
* `interval_relocate: str`: The mode for the frequency of the relocation operations. Can be one of the following: `"fixed", "min", "max"`
* `interval_container_monitor: float`: The interval in which the NLC checks for new containers.
* `gain_reduce: int`: The gain with which the quota of a container is reduced when its tasks meet all deadlines. The formula can be found in [this paper]().
* `gain_increase: int`: The gain with which the quota of a container is increased, when its tasks miss deadlines. The formula can be found in [this paper]().
* `tuf_active: int`: `0` to deactivate the use of TUFs. `1` to activate them
* `id_string`: The string which must be part of the name of every RT Docker container. The NLC uses this string to identify RT Docker containers.
* `proc_update_tasks`: The path to the `update_tasks` `/proc` entry.
* `proc_send_tu`: The path to the `send_tu` `/proc` entry.
* `proc_get_temporal_errors`: The path to the `get_tmp_err` `/proc` entry.
* `relocate_error_code`: The error code which is sent to the self-orchestration tool, when a container should be relocated.
* `self_orchestration_url`: The URL to which a request for relocation is sent.

KM Communication Protocol
-------------------------

There are three functions the KM offers via the `/proc` filesystem. The NLC calls them to read data from the KM and write data back. The following sections explain the protocol used in these three functions in a pseudo-regex fashion.

  - Update Tasks: This function is called when the NLC detects a new container. The message contains information about the tasks inside the container that is required by the KM.

    n_tasks_in_container,container_process_name,min_quota\n
    (task_process_name,period,deadline\n){n_tasks_in_container}
 
    **Variables**
    * `n_tasks_in_container`: The number of processes inside the container.
    * `container_process_name`: The name of the entrypoint process. Usually a script. This is **not** the container name known by Docker.
    * `min_quota`: The quota the container must at least have.
    * `task_process_name`: The name of a process inside the container that is called by the entrypoint script and shall be adapted by the KM.
    * `period`: The period of the process.
    * `deadline`: The deadline of the process.

  - Get Temporal Error: This function is used by the NLC to retrieve the average temporal errors for every task. The message that is sent by the KM has the following format.

    (container_process_name:container_marked\n
    (task_process_name,avg_tmp_err){n_tasks_in_container}){n_containers}

    **Variables**
    * `n_tasks_in_container`: The number of processes inside the container.
    * `n_containers`: The number of RT Docker containers on the node.
    * `container_process_name`: The name of the entrypoint process. Usually a script. This is **not** the container name known by Docker.
    * `task_process_name`: The name of a process inside the container that is called by the entrypoint script and shall be adapted by the KM.
    * `container_marked`: `0` if everything is fine and `1` if the container should be relocated.
    * `avg_tmp_err`: The average temporal error of the task since the last call of this function.

  - Send TU: This function is used by the NLC to send calculated utility of the container back to the KM. The containers are sorted by ascending utility such that those containers with a low utility have a higher chance for a quota increase.

    (container_process_name,utility){n_containers}

    * `n_containers`: The number of RT Docker containers on the node.
    * `container_process_name`: The name of the entrypoint process. Usually a script. This is **not** the container name known by Docker.
    * `utility`: The utility value of the container ([0, 100]):



Developer guide
===============

Authors
=======
Stefan Walser

License
=======
Copyright (C) TTControl (2024)

All rights reserved.

This document contains proprietary information belonging to TTControl.
Passing on and copying of this document, and communication
of its contents is not permitted without prior written authorization.

VERSION      : 1

DATE         : 15.12.2023

AUTHOR       : Stefan Walser

Notice (dependencies)
=====================