docs:rtlib:recipes

Recipes

From the application side, the mandatory requirement to exploit the BarbequeRTRM is to provide an implementation that allows it to be run-time reconfigurable.

From the BarbequeRTRM side, the configuration of an application is characterized in terms of set of resource requirements, and is called Application Working Mode (AWM).

The application must declare to the BarbequeRTRM the list of its Application Working Modes. Such list must be provided through a file called, in jargon, Recipe. which basically is an XML file.

Please note that a recipe file must satisfy some requirements:

  • The file name must terminate with .recipe extension.
  • The recipe must be installed under out/etc/bbque/recipes. This step is automatically performed by the BOSP building system if the application is properly integrated.

Since make clean and make distclean purge the content of directory out/ remember to keep a copy of your recipe in a safe place.

  • AWM IDs must be sequentially numbered, starting from 0.
  • A <platform> section with the id matching the target platform must be defined.

As a convention, the higher is the AWM ID number, the greater is the amount of resource requirements specified.

Example

<?xml version="1.0"?>
<BarbequeRTRM version="0.8">
    <application name="BbqueTestApp" priority="4">
 
    <!-- Generic Linux -->
        <platform id="org.linux.cgroup">
            <awms>
            <!-- AWM 0 -->
                <awm id="0" name="LowQ" value="1" config-time="5">
                    <resources>
                        <cpu>
                            <pe qty="100"/>
                            <mem qty="100" units="M">
                        </cpu>
                    </resources>
                </awm>
            <!-- AWM 1 -->
                <awm id="1" name="MedQ" value="2" config-time="5">
                    <resources>
                        <cpu>
                            <pe qty="200"/>
                            <mem qty="100" units="M">
                        </cpu>
                    </resources>
                </awm>
            <!-- AWM 2 -->
                <awm id="2" name="HighQ" value="4" config-time="5">
                    <resources>
                        <cpu>
                            <pe qty="400"/>
                            <mem qty="150" units="M">
                        </cpu>
                    </resources>
                </awm>
            </awms>
        </platform>
       <platform id="org.linux.cgroup" hw="exynos_5420">
            <awms>
            <!-- AWM 0 -->
                <awm id="0" name="LowQ" value="1" config-time="7">
                    <resources>
                        <cpu>
                            <pe qty="100"/>
                            <mem qty="100" units="M">
                        </cpu>
                    </resources>
                </awm>
            <!-- AWM 1 -->
                <awm id="1" name="MedQ" value="2" config-time="7">
                    <resources>
                        <cpu>
                            <pe qty="200"/>
                            <mem qty="100" units="M">
                        </cpu>
                    </resources>
                </awm>
            <!-- AWM 2 -->
                <awm id="2" name="HighQ" value="4" config-time="8">
                    <resources>
                        <cpu>
                            <pe qty="400"/>
                            <mem qty="150" units="M">
                        </cpu>
                    </resources>
                </awm>
            </awms>
        </platform>
    </application>
</BarbequeRTRM>

When the application instantiates the Execution Context, and thus specifies the recipe to use, the BarbequeRTRM checks the validity of the recipe.
Here below the complete set of tags and attributes is listed. Some tags or attributes can be optional. Concerning the hierarchy of the different XML elements, please consider the example provided above.

  • BarbequeRTRM: The root tag, including general attributes.
  • recipe_version Since the format of the recipes can change in future versions of the framework, a first validation step requires to specify the reference version of the recipe.
  • application: Application/EXC properties.
  • name: [optional] A descriptive name of the application/EXC.
  • priority: Static priority assigned. Generally this is taken into account at run-time by the resource allocation policy. It is mandatory to provide a value between 0 and N, where value 0 denotes the highest priority level (critical application). The lowest possible level N can be specified in the configuration of the BOSP building.
  • platform: The target system. The recipe can contain more than one platform section.
  • id: The string identifier of the platform. The recipe must contain at least the platform section with the id matching the one of system platform. The options supported by the current release of the framework are “org.linux.cgroup” (a Linux-based system featuring Control Groups) and “it.polimi.bbque.tpd”. The latter is parsed only in case of Test Platform Data (TPD) option enabled in the BarbequePlatform configuration menu.
  • hw: [optional] This specifies the target platform from the point of view of the hardware (e.g., a SoC). The current BarbequeRTRM version supports the following hardware identifiers: “exynos_5410”, “exynos_5420”, “omap_4470”.
  • awms: The section listing the set of AWMs.
  • awm : Definition of a single AWM. A valid recipe must defines at least one AWM.
  • id : Each AWM is identified by a number. It is strictly mandatory that the numeration starts from 0 and continue in a sequence of integer values.
  • name : A descriptive name for the AWM (e.g., “high-quality”,“mid-quality”, “low-quality”).
  • value: A preference value associated to the AWM. If the value is expression of a performance level, in most cases the highest is the value the greater is the requirement of resources. In the example provided, a direct proportionality has been applied between the amount of resources and the value associated.
  • config-time: [optional] Specify the time spent to configure the application in the given Application Working Mode.
  • resources: The section listing the resource requirements of the AWM. All che children tags nested into this section are considered resource names. The hierarchy of the nesting and the ID specified are used to build the “resource path”, i.e. a namespace-style string identifying the specific resource. For instance, in the example the recipe would produce the following resource paths: cpu.pe and cpu.mem.
  • sys and cpu: Used to group resources into a two-level hierarchical partitioning. Specifically, sys references a system, thought as a single working machine or board. This is an optional tag if the target platform is not a distributed computational system. In other words, on a common desktop or embedded board we can avoid to specify it.


The cpu tag references a computational node, e.g., a processor, usually featuring a set of multiple cores sharing one or more cache memory levels.
mem: The amount of memory required. Please consider the hierarchical position to reference the correct level of memory. pe : The amount of processing requirements in terms of CPU time quota (percentage). For instance, in AWM 2 the recipe requires a 200%, meaning that we need a full usage of 2 CPU cores.

  • units: A qualifier for the attribute qty. Values actually supported are %, Kb, Mb, Gb.
  • qty: The amount required.

Next tutorial: The Linux Control Groups.

docs/rtlib/recipes.txt · Last modified: 2015/11/17 12:35 by slibutti

Page Tools