.adef files can contain these sections:

Bindings

Bindings allow client-side IPC API interfaces (listed in the requires sections of Component.cdef files) to be bound to server-side interfaces (listed in the provides sections of Component.cdef files).

This gives direct control over how IPC interfaces are interconnected so reusable components and/or apps can be bound (wired) together to form a working system.

Bindings can be between two interfaces inside the same app (internal binding), or can be between a client-side interface in an app and a server-side interface provided by another app (or non-app user).

Interface instances inside the app use the executable name, component name, and the service instance name separated by a period (‘.’).

The client interface always appears first with an arrow ( -> ) to separate the client interface from the server interface.

Here's a code sample binding clientExe.clientComponent.clientInterface to serverExe.serverComponent.serverInterface:

bindings:
{
    clientExe.clientComponent.clientInterface -> serverExe.serverComponent.serverInterface
}

External services provided by other apps use the app name and the service name, separated by a period ('.'):

bindings:
{
    clientExe.clientComponent.clientInterface -> otherApp.serverInterface
}

To bind to a service provided by a non-app user, the app name is replaced by a user name inside angle brackets:

bindings:
{
    clientExe.clientComponent.clientInterface -> <root>.serverInterface
}

If client-side code was built using the ifgen tool or mkcomp or mkexe with requires or bundles sections, the tool reading your .adef file won't know about the client-side interface. Use a special work-around to bind those interfaces:

bindings:
{
    *.le_data -> dataConnectionService.le_data
}

This would bind any unknown client-side le_data interfaces in the current app to the le_data server-side interface on the dataConnectionService app.

Bundles

Lists additional files or directories to be copied from the build host into the app so they’re available to the app at runtime (e.g., audio files, web pages, executable scripts or programs built using some external build system).

bundles:
{
    file:
    {
        // Include the web server executable (built using some other build tool) in the app's /bin.
        [x] 3rdParty/webServer/bin/wwwServ  /bin/

        // Put the company logo into the app's /var/www/ for read-only access by the web server.
        images/abcCorpLogo.jpg  /var/www/

        // Make the appropriate welcome page for the product appear at /var/www/index.html.
        webContent/$PRODUCT_ID/welcome.html  /var/www/index.html

        // Create a file to record persistent custom audio messages into.
        [w] audio/defaultMessage.wav  /usr/share/sounds/customMessage.wav
    }

    dir:
    {
        // Recursively bundle the directory containing all the audio files into the app.
        // It will appear to the app read-only under /usr/share/sounds/.
        audio   /usr/share/sounds
    }
}

Three things need to be specified for each file or directory:

access permissions
build system path
target path

Access permissions - any combination of one or more of the following letters, enclosed in square brackets:

r = readable
w = writeable
x = executable

If permissions values are not specified, then read-only ([r]) is the default.

Directories always have executable permission set so they can be traversed. Setting the [x] permission in the dir: subsection causes the files under the directory to be made executable.

Setting [w] in the dir: subsection causes all files under that directory to be writeable, but the directory itself will not be writeable.

Note: Directories in the persistent (flash) file system are never made writeable because the on-target flash file system does not support usage quotas (yet).

Build system path - file system path on the build PC where the file is located at build time.

The path can be relative to the directory where the .adef file is located.

Note: Environment variables can be used inside these paths.

Target path - file system path on the target where the file will appear at runtime.

It's an absolute path inside the app's sandbox file system.

If the path ends with '/', it means the directory path where the source object (file or directory) will be copied. The destination object will have the same name as the source object.

If the path doesn't end in a '/', it's a full destination object path. The destination object could have a different name than the source object.

Note: If the app is running unsandboxed, the bundled files and directories can be found in their installation location under /opt/legato/apps/xxxx, where xxxx is replaced by the app name.

Quoting Paths

File paths can be enclosed in quotation marks (either single ' or double "). This is required when the file path contains spaces or comment start sequences

"//" or  "/*"

File Ownership and Set-UID Bits

When the app is installed on a target:

the owner and group are set to root on all files in the app.
the setuid bit is cleared on everything in the app.

Overriding .cdef

If a file is bundled by a component's .cdef file and another file is bundled to the same target path by the .adef, then the file specified by the .adef will be bundled into the app.

If a directory is bundled by a component's .cdef file and another directory is bundled to the same target path by the .adef, then the two directories will be merged into the bundle, where conflicts are resolved by omitting the file from the directory specified by the .cdef.

CPU Share

Specifies the relative cpu share for an app.

Cpu share calculates the cpu percentage for a process relative to all other processes in the system. New cgroups and processes default value of 1024 if not otherwise configured. The actual percentage of the cpu allocated to a process is calculated like this:

(share value of process) / (sum of shares from all processes contending for the cpu)

All processes within a cgroup share the available cpu percentage share for that cgroup like this:

cgroupA is configured with the default share value, 1024.
cgroupB is configured with 512 as its share value.
cgroupC is configured with 2048 as its share value.
cgroupA has one process running.
cgroupB has two processes running.
cgroupC has one process running.

This assumes all processes in cgroupA, cgroupB and cgroupC are running and not blocked waiting for an I/O or timer event, and another system process is also running.

Sum of all shares (including the one system process) is 1024 + 512 + 2048 + 1024 = 4608

The process in cgroupA will get 1024/4608 = 22% of the cpu. The two processes in cgroupB will share 512/4608 = 11% of the cpu, each process getting 5.5%. The process in cgroupC will get 2048/4608 = 44% of the cpu. The system process will get 1024/4608 = 22% of the cpu.

cpuShare: 512

Although apps aren't limited to running inside a sandbox (i.e., unsandboxed apps), the Supervisor still enforces limits. Ensure cpuShare values are set high enough for unsanboxed apps. Also see Max File Bytes.

Executables

Lists executables to be constructed and moved to the bin directory inside the app.

An executable’s content is specified as a list of components.

executables:
{
    myExe = ( myComponent otherComponent )
}

Each component included in an executable will be built and linked into the executable and its COMPONENT_INIT function will be run at process start-up. The component’s runtime files (shared libraries, source code, etc.) will be packaged inside the app to be installed on the target.

The mechanisms used to construct executables and components depend on the type of content and the target device.

C and C++ files will be compiled and linked using the appropriate compiler tool chain based on the target.

(In the future) Java code will be compiled to Java bytecode, and interpreted code, such as Python code will be simply copied into the app.

Note: There may be incompatibilities between components that prevent them from being included in the same executable (e.g., Java component and C components in the same executable together). The build tools will advise if there's a problem.

Groups

Add an app's user to groups on the target system.

groups:
{
    www-data
    modem
}

Max File System Bytes

Specifies the maximum amount of RAM that can be consumed by an app's temporary (volatile) file system at runtime.

Default is 128K

maxFileSystemBytes: 120K

Note: The file system size will also be limited by the maxMemoryBytes limit.

Max Memory Bytes

Specifies the maximum amount of memory (in bytes) that all processes in an app can share. Default is 40960K (40MB).

maxMemoryBytes: 1000K

Note: Will be rounded to the nearest memory page boundary.

Max MQueue Bytes

Specifies the maximum number of bytes that can be allocated for POSIX MQueues. Default is 512.

maxMQueueBytes: 16K

Max Queued Signals

Specifies the maximum number of signals that can be waiting for delivery to processes in the app.

This limit will only be enforced when using sigqueue() to send a signal. Signals sent using kill() are limited to at most one of each type of signal anyway.

Default is 100.

maxQueuedSignals: 200

Max Threads

Specifies the maximum number of threads allowed to run at one time: an integer number.

Note: A single-threaded process (a running program that doesn't start any threads other than the one running the main() function) counts as one thread.

If fork() calls or pthread_create() calls start failing with error code EAGAIN (seen in strace output as clone() system calls), then you are probably running into this limit.

Default is 20.

maxThreads: 4

Max Secure Storage Bytes

Specifies the maximum number of bytes that can be stored in Secure Storage.

Default is 8K.

maxSecureStorageBytes: 4K

Pools

Warning: This feature not yet implemented.

Sets the number of memory pool blocks in a memory pool in a given component in a given process.

This overrides any setting for the same pool in the pools: section of the Component.cdef file.

pools:
{
    myProc.myComponent.myPool = 100
}

Processes

A processes section specifies processes to run when the app is started including environment variables, command-line arguments, limits, and fault handling actions.

The processes section is divided into subsections.

If different processes have different variables, they must be in separate processes: sections.

processes:
{
    // Start up these processes when the app starts
    run:
    {
        myProc1 = ( myExe --foo -b 43 )
        myProc2 = ( myExe –bar --b 92 )
        ( myExe2 "Hello, world." )  // If no proc name is specified, uses the exe name by default.
    }

    // Env var settings (name = value) for all processes in this section.
    envVars:
    {
        LE_LOG_LEVEL = DEBUG
    }

    priority: medium    // Starting (and maximum) scheduling priority.
                        // Process can only lower its priority from here.

    maxCoreDumpFileBytes: 100K  // Maximum size of core dump files.
    maxFileBytes: 50K           // Files are not allowed to grow bigger than this.
    maxLockedMemoryBytes: 32K   // Can't mlock() more than this many bytes.
    maxFileDescriptors: 20      // Can't have more than this number of FDs open at the same time.
}

processes:
{
    run:
    {
        ( realTimeExe )
    }

    priority: rt10   // Allow real-time scheduling (max priority 10) for processes in this section.

    /*-- Exception handling policy for processes in this section. --*/
    faultAction: restart   // Restart the process if it fails.
}

Run

Names a process to be started by the Supervisor when the app is started. Also specifies executable and command-line arguments.

run:
{
    myProc1 = ( myExe --foo -b 43 )
}

Process name and command-line arguments are optional.

run:
{
    ( myexe )
}

If the process name is not specified, then the process will be given the same name as the executable it's running (e.g. myexe)

A given executable can be launched multiple times.

run:
{
    process1 = ( myexe )
    process2 = ( myexe )
}

Command-line arguments passed to the process when started can appear after the executable name.

run:
{
    ( myexe --foo )
}

run:
{
    ( myexe --bar  // Note that the command-line can be broken into multiple lines for readability.
            --toto ) // And it can be commented too.
}

Executable names can be the ones listed in the app’s executables: section. They can also be the names of files that are bundled into the app with [x] (executable) permission.

Quotation marks (either single ' or double ") can be used if white-space (spaces, tabs, //, etc.) is needed inside a command-line argument, or if an empty argument is needed ("").

Env Vars

Environment variables appear as name = value pairs. First is the environment variable name and second is the variable value.

Enclose the value in quotation marks (either single ' or double ") if white-space is required:

envVars:
{
    LE_LOG_LEVEL = DEBUG
    MESSAGE = "The quick brown fox jumped over the lazy dog."
}

Fault Action

Specifies the action the Supervisor should take when the process terminates with a non-zero exit code or because of an un-caught signal (e.g., SIGSEGV, SIGBUS, SIGKILL).

Possible values are:

ignore - Supervisor just logs a warning message; no further action taken.
restart - log a critical message and restart the process.
restartApp - log a critical message and restart the entire app.
stopApp - log a critical message and terminate the entire app (send all processes the SIGTERM signal, followed shortly by SIGKILL).
reboot - log an emergency message and reboot the system.

Default is ignore.

faultAction: restart

Priority

Specifies the starting (and maximum) scheduling priority. A running app process can only lower its priority from this point. Once it has lowered its priority, it can't raise it again (e.g., if the process starts at medium priority and reduces to low priority, it can't go back to medium priority). The default is medium.

Values:

idle - for low priority processes that get CPU time only if no other processes are waiting.
low, medium, high - intended for normal processes that contend for the CPU. Processes with these priorities don't preempt each other, but their priorities affect how they're inserted into the scheduling queue (high to low).
rt1 to rt32 - intended for (soft) realtime processes. A higher realtime priority will preempt a lower realtime priority (ie. rt2 would preempt rt1). Processes with any realtime priority will preempt processes with high, medium, low and idle priorities.

Warning: Processes with realtime priorities preempt the Legato framework processes. Ensure that your design lets realtime processes relinquish the CPU appropriately.

priority: medium

Max Core Dump File Bytes

Specifies the maximum size (in bytes) of core dump files that can be generated by processes.

Default is 8K

Note: Core dump file size is limited by Max File Bytes. If the the core file is generated in the sandbox's temporary runtime file system, it 'll also be limited by Max File System Bytes.

maxCoreDumpFileBytes: 100K
maxFileBytes: 100K
maxFileSystemBytes: 200K

Max File Bytes

Specifies the maximum size processes can make files. The K suffix permits specifying in kilobytes (multiples of 1024 bytes).

Default is 88K

maxFileBytes: 200K

Exceeding this limit results in a SIGXFSZ signal sent to the process. By default, this kills the process, but it can be blocked or caught to receive an error with errno set to EFBIG.

Although apps aren't limited to running inside a sandbox (i.e., unsandboxed apps), the Supervisor still enforces limits. Ensure maxFileBytes values are set high enough for unsanboxed apps. Also see CPU Share.

Note: If the file is in the sandbox's temporary runtime file system, the file size will also be limited by Max File System Bytes and Max Memory Bytes.

Max File Descriptors

Specifies the maximum number of file descriptors a process can have open at one time.

Default is 256

maxFileDescriptors: 100

Max Locked Memory Bytes

Specifies the maximum bytes of memory the process can lock into physical RAM (e.g., using mlock() ).

Can't be higher than Max Memory Bytes.

Default is 8K

maxLockedMemoryBytes: 100K

Note: Also limits the maximum number of bytes of shared memory the app can lock into memory using shmctl().

Watchdog Action

Specifies the action the Supervisor should take when a process subscribed to the watchdog service fails to kick the watchdog before it expires. Possible values are the same as in Fault Action as well as:

stop - Supervisor terminates the process if it's still running. If a watchdog action has not been supplied, the default action will restart the process.

Watchdog Timeout

Specifies the timeout length (in milliseconds) for watchdogs called by processes in the enclosing processes section.

Once a process has called le_wdog_Kick(), it's registered with the software watchdog service. If it then fails to call le_wdog_Kick() within the given timeout, the Supervisor is notified will take the action specified in Watchdog Action

watchdogTimeout: 10000 // Must call le_wdog_Kick() at least every 10 seconds.

A special value "never" is permitted for this section. If used, the watchdog will never time out.

watchdogTimeout: never  // Disable watchdog for these processes.

Extern

Declares that an IPC API interface is available for binding via .sdef file's bindings section or .adef file's bindings section.

extern:
{
    exeName.componentName.interfaceName
}

Internal interface instances are identified by the executable, component, and interface names. The different interface instance identifier parts are separated by a period (‘.’).

Outside the app, the interface will be identified using the app name and the interface name (appName.interfaceName), thereby hiding from other apps the details of what executable and component within the app implements the interface.

To have other apps see an interface with a different name, add differentName = in front of the interface specification:

extern:
{
    differentName = exeName.componentName.interfaceName
}

The interface will then appear outside the app as appName.differentName.

Server-Side Example

This code sample declares the temperature interface on the thermistor component in the sensor executable should be made into a bindable external server-side interface (service) called spaceTemp:

extern:
{
    spaceTemp = sensor.thermistor.temperature
}

If the app was called thermometer, then other apps could bind their client-side interfaces to thermometer.spaceTemp to receive temperature readings from this sensor app.

Client-Side Example

This code sample declares that the temperature interface on the tempInput component in the controller executable should be made into a bindable external interface:

extern:
{
    controller.tempInput.temperature
}

If this app were called thermostat, then to outsiders (e.g., in a .sdef file or another app's .adef file), the interface would be called thermostat.temperature.

Requires

The requires: section specifies things the app needs from its runtime environment.

It can contain various subsections.

Config Tree

Declares the app requires access to a specified configuration tree. Each app has its own configuration tree named after the app. There's also a system configuration tree that contains privileged system data.

By default, an app only has read access to its own configuration tree.

Apps can be granted read access or both read and write access to trees using an optional access permission specifier:

[r] - grant read-only access
[w] - grant read and write access

If access is granted to a tree, but the access mode ([r] or [w]) is not specified, only read permission will be granted.

A special tree name "." can be used to refer to the app's own configuration data tree.

requires:
{
    configTree:
    {
        [w] .       // I need write access to my configuration data.
        otherApp    // I need read access to another app's configuration data.
    }
}

Warning: Because config data can be saved to flash storage, granting write access to a config tree can make it possible for the app to wear out your flash device. Granting an untrusted app write access to another app's config settings creates a security hole, because it makes it possible for the untrusted app to interfere with the other app's operation. It's especially dangerous to grant write access to the system tree, because it's possible to completely compromise the target device. Even read access may be dangerous if any kind of security key, including PIN and PUK codes, are kept in the system tree. Don't give apps direct access to the system tree.

Dir

Used to declare directories located on the target outside of the app that are to be made accessible to the app.

The location inside the app's sandbox where the directory will appear is also specified.

Things listed here are expected to be found on the target at runtime. They are not copied into the app at build time; they are made accessible to the app inside of its sandbox at runtime.

Each entry consists of two file system paths:

The first path is the path to the directory outside of the app. This must be an absolute path (beginning with "/") and can never end in a "/".
The second path is the absolute path inside the app’s sandbox where the directory will appear at runtime.

Paths can be enclosed in quotation marks (either single ' or double "). This is required when it contains spaces or character sequences that would start comments.

If the destination path ends in a "/", the name from the source is appended to it. Otherwise, only the destination path is used. That means /foo/bar /baz will appear as /baz inside the sandbox, and /foo/bar /baz/ will appear as /baz/bar inside the sandbox.

requires:
{
    dir:
    {
        // I need access to /proc for debugging.
        /proc   /

        // For now, I want access to all executables and libraries in /bin and /lib.
        // Later I'll remove this and replace with just the files I really need in the field.
        // Also, I don't want to hide the stuff that the tools automatically bundle into my app's
        // /bin and /lib for me, so I'll make the root file system's /bin and /lib accessible as
        // my app's /usr/bin and /usr/lib.
        /bin    /usr/bin
        /lib    /usr/lib
    }
}

Note: Even though the directory appears in the app's sandbox doesn't mean the app can access it. The directory permissions settings must also allow it. File permissions (both DAC and MAC) and ownership (group and user) on the original files in the target system remain in effect inside the sandbox.

Warning: Any time anything is made accessible from inside an app sandbox, the security risks must be considered carefully. Ask yourself if access to the object can be exploited by the app (or a hacker who has broken into the app) to access sensitive information or launch a denial-of-service attack on other apps within the target device or other devices connected to the target device?

Note: It's not possible to put anything inside of a directory that was mapped into the app from outside of the sandbox. If you require /bin to appear at /usr/bin, you can't then bundle a file into /usr/bin or require something to appear in /usr/bin; that would have an effect on the contents of the /bin directory outside of the app.

File

Declares:

specific files located on the target outside of the app, but made accessible to the app.
location inside the app's sandbox where the file will appear.

Things listed in requires are expected to be found on the target at runtime. They're not copied into the app at build time; they are made accessible to the app inside of its sandbox at runtime.

Each entry consists of two file system paths:

path to the object in the file system outside of the app, which must be an absolute path (beginning with ‘/’).
absolute file system path inside the app’s sandbox where the object will appear at runtime.

A file path can be enclosed in quotation marks (either single ' or double "). This is required when it contains spaces or character sequences that would start comments.

The first path can't end in a '/'.

If the second path ends in a '/', then it's specifying the directory where the object appears, and the object has the same name inside the sandbox as it has outside the sandbox.

requires:
{
    file:
    {
        // I get character stream input from outside via a named pipe (read-only)
        /var/run/someNamedPipe  /var/run/

        // I need to be able to play back audio files installed in /usr/local/share/audio.
        "/usr/local/share/audio/error message.wav" /usr/share/audio/
        '/usr/local/share/audio/success message.wav' /usr/share/audio/
    }
}

Note: Even though the file system object appears in the app's sandbox it still needs permissions settings on the file. File permissions (both DAC and MAC) and ownership (group and user) on the original file in the target system remain in effect inside the sandbox.

It's also possible to give the object a different names inside and outside of the sandbox by adding a name to the end of the second path.

requires:
{
    file:
    {
        // Program uses /var/run/someNamedPipe which it calls /var/run/externalPipe.
        /var/run/someNamedPipe  /var/run/externalPipe
    }
}

Warning: When something is accessible from inside an app sandbox, there are potential security risks (e.g., access to the object could be exploited by the app, or hacker, to access sensitive information or launch a denial-of-service attack on other apps within the target device or other devices connected to the target device).

Device

Declares:

device files that reside on the target outside of the app, but made accessible to the app.
location inside the app's sandbox where the file will appear.
access permissions the app is given to the device file.

Things listed in requires are expected to be found on the target at runtime. They're not copied into the app at build time; they are made accessible to the app inside of its sandbox at runtime.

Each entry consists of two file system paths and a set of optional access permissions:

access permissions, readable ([r]) and/or writeable ([w]). Executable is not allowed on device files. If permission values are not specified, then read-only ([r]) is the default.
path to the object in the file system outside of the app, which must be an absolute path (beginning with ‘/’). This must be a path to a valid character or block device file.
absolute file system path inside the app’s sandbox where the object will appear at runtime.

A file path can be enclosed in quotation marks (either single ' or double "). This is required when it contains spaces or character sequences that would start comments.

The first path can't end in a '/'.

If the second path ends in a '/', then it's specifying the directory where the object appears, and the object has the same name inside the sandbox as it has outside the sandbox.

requires:
{
    device:
    {
        // I get read-only access to the SPI port.
        [r]     /dev/sierra_spi   /dev/sierra_spi

        // I get read-only access to the NMEA port.
                /dev/nmea         /dev/nmea

        // I get read and write access to the I2C port.
        [rw]    /dev/sierra_i2c   /dev/
    }
}

Note that if a hot-plug device is unplugged and plugged back in, the app must be restarted before it can access the device.

It's also possible to give the object a different names inside and outside of the sandbox by adding a name to the end of the second path.

requires:
{
    device:
    {
        /dev/ttyS0  /dev/port1     // Program uses /dev/port1, but UART0 is called /dev/ttyS0.
    }
}

Warning: When something is accessible from inside an app sandbox, there are potential security risks (e.g., access to the object could be exploited by the app, or hacker, to access sensitive information or launch a denial-of-service attack on other apps within the target device or other devices connected to the target device).; This section is experimental. Future releases of may not support this section.

Sandboxed

Specifies if the app will be launched inside a sandbox.

Permitted content in this section is:

true - app will be run inside of a sandbox.
false - app won't be run in a sandbox.

The default is true.

If an app is unsandboxed (app is not inside of a sandbox), it can see the target device's real root file system. A sandboxed app can't see the target's real root file system; a sandboxed app has a separate root file system, which it can't leave.

Each app has its own user and primary group IDs. The app's user name and primary group name are both appxxxx", where the xxxx is the name of the app.

User and/or group will be automatically created if missing for the specified app, but only users and groups of sandboxed apps will automatically be deleted when those apps are uninstalled.

sandboxed: false

Start

Specifies if the app should start automatically at start-up:

auto starts automatically by the Supervisor.
manual" starts through manual prompt to the Supervisor. Default is auto.

start: auto

Version

Optional field that specifies a string to use as the app's version string.

version: 0.3a

Note

The –append-to-version option to mkapp can be used to add to the app's version string.
app foo version can be run on-target to get the version string of the app called "foo".

Watchdog Action

The watchdogAction section sets the recovery action to take if a process in this app expires its watchdog. This value will be used if there is no value set in the processes section for a given process. See Watchdog Action in the processes section.

Watchdog Timeout

The watchdogTimeout section sets the default timeout in milliseconds for processes in this app. Will be used if there's no value set in the processes section for a given process. See Watchdog Timeout in the processes section.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.