.. _build-Kconfig:

Build Configuration with Kconfig
--------------------------------

To configure the compilation options of the framework execute:

.. code-block:: bash

	$ make menuconfig

.. image:: img/bbque_kconfig_root.png

Once the menu has appeared, we can navigate through it as it follows:


.. _kconfig-hw:

Target Hardware
^^^^^^^^^^^^^^^

.. image:: img/bbque_target_hw.svg

In the configuration of the target hardware platform, first, we must choose the
``Host System`` option. This typically includes the combination of the
operating system, the CPU architecture family and the native or
cross-compilation mode.

  - ``Linux - Native``: compile for the local host system
  - ``Linux - Cross-compile ARM``: cross-compile for an ARM-based embedded board
  - ``Android - Cross-compile ARM``: cross-compile for an Android device

Going one level back, we have a further option that affects the host system
configuration: *Emulated Host (cgroup)*. When selected, the BarbequeRTRM will
run without actually enforcing any resource assignment, for resources of type
CPU (and related processing elements) and MEMORY (host-side). This option can
be useful for some framework development purposes, or in case of development of
integrated applications. In the latter, the developer may be interested in
testing the integration, without taking care of the resource assignment.

The second aspect of the target hardware is related to the ``Acceleration
Platform``. The configuration menu includes the possibility of enabling the
support for additional processing units, through *OpenCL* and the *NVIDIA
run-time*. Special cases instead are the ones included in the *FPGA-Based
Platform* menu. Here it is possible to choose between the H2020 projects
*MANGO* and *RECIPE*. This requires the availability of the specific
hardware developed for the two research projects. As an alternative, the option
*Emulate Accelerators*, similarly to Emulated Host, allows the developers to
test the framework in an emulated configuration, also for the heterogeneous
part. In case of selection of one of the FPGA-based options, the *MANGOLIBS
Installation path* must be specified, providing the path to the root
installation directory containing the other libraries and frameworks, the
software stack is based on.

Heterogeneous target platforms from EU H2020 projects
"""""""""""""""""""""""""""""""""""""""""""""""""""""


 - `The BarbequeRTRM on the H2020 MANGO Platforms <https://bosp.deib.polimi.it/lib/exe/fetch.php?media=docs:pdfs_mango_user_guide.pdf>`_

 - `The BarbequeRTRM and the H2020 RECIPE Platforms <https://docs.google.com/document/d/1L3_ngQKDtHlKq1ig5bq0IX6lfRl1dFYQzUh-_SQdoEI/edit?usp=sharing>`_

.. _kconfig-deploy:

Deployment
^^^^^^^^^^

This submenu allows you to specify the installation directory of the framework
and, in case of cross-compilation, all the data required to establish a SSH
connection towards the target device.

.. _kconfig-rtrm:

Run-Time Resource Manager
^^^^^^^^^^^^^^^^^^^^^^^^^

This submenu includes the options regarding the BarbequeRTRM daemon and the
libraries provided to the application developers.

.. _kconfig-daemon:

Daemon Setup
""""""""""""

This is the menu containing the resource manager daemon specific options, which
include:

  - ``Platform Loader``: tools to be used for reading the target platform
    description (RXML is the default and suggested one).
  - ``Linux Resource Manager``: Linux-specific management options. Here we can
    enable the *Linux Process Management* option for enabling the management
    of legacy workload, i.e. applications not implementing the Adaptive Execution
    Model provided by the RTLib.
  - ``Power Management``: the power management capabilities of the
    BarbequeRTRM. Through this menu, the user can enable the resource-specific
    power monitor and control interfaces (CPU, AMD/NVIDIA GPUs, MANGO,...).
    Moreover, we may want periodic run-time monitoring of the platform (*Periodic
    Monitoring*), with the period length to be set in the daemon configuration
    file.  The *Battery Management* option instead, if enabled, allows us to
    trigger the current policy in case of charge status under a given threshold.
    Obviously, the policy should include an energy-aware approach. Finally, the NO
    ACPI Interface is the default selection for target hosts based on a Linux
    kernel version >= 4.
  - ``Distributed Systems``: the set of options for enabling the BarbequeRTRM
    in a distributed context. The *Server port* value is the port number for
    the daemon to wait for a connection. The *Agent Proxy plugin* requires the
    selection of an implementation of the RPC interface onto which it will be based
    the communication between remote instances of the resource manager. Finally,
    the *Distributed Configuration* selection can drive the behaviour of the
    resource allocation policy.


.. _kconfig-policies:

Policies
""""""""

.. list-table:: Resource Allocation Policies
   :header-rows: 1
   :width: 80%

   * - Name
     - Description
     - Recipe-based
     - Process support
   * - DynamicRandom
     - Random assignment of CPU quota.
     - No
     - Yes
   * - Random
     - Random assignment of Application Working Mode.
     - Yes
     - Yes
   * - TempBalance
     - Priority-proportional and thermal-aware allocation of CPUs.
     - No
     - Yes
   * - Test
     - Priority-proportional allocation of CPUs.
     - No
     - Yes
   

Run-Time Library 
"""""""""""""""""

In this menu, you can find some configuration options for the Run-time Library
(**bbque_rtlib**), including the maximum length for the application name, the
timeout related to the communication bewteen application and daemon, the selection of
the type of channel and the profiling options.


Programming Model
"""""""""""""""""

On top of the *Adaptive Execution Model* we built also an intermediate layer
for the integration of further programming models: the **Programming Model Synchronization Layer**.
In the current version, BOSP provides also the task-graph library (**libtg**),
to implement programming models based on providing a task-graph based
description of the managed application.
A first example of programming model exploiting this feature comes with the *MANGO Library* included
in the `MANGOLIBS Project <https://bitbucket.org/mango_developers/mangolibs/src/master/>`_.


Advanced Options 
""""""""""""""""

Advanced options include the possibility of enabling a Debug build, the maximum
number of application priorities, number of managed resources (per type), the
selection of additional optional managers (**Event Manager** or **Data
Manager**) and the policy profiler.


External Libraries and Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This menu groups two types of components: dependency libraries and tools.
The dependencies are typically automatically selected, according to the
configuration options enabled above.


.. _kconfig-applications:

AEM-integrated applications
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sample applications and samples from benchmark suites ported to the
:ref:`aem-applications`.