System Definition .sdef

.sdef files can contain these sections:

apps

An apps: section declares one or more apps to be deployed to the target system.

apps:
{
    webserver
}

This looks for an app definition file called webserver.adef and includes it in the system.

The apps: section can override limits and other app settings.

Here's a code sample to deploy a web server limiting its share of the CPU under heavy load to 500 (see CPU Share):

apps:
{
    webServer
    {
        cpuShare: 500
    }
}

Any of the following subsections can be used in an .sdef apps: section, and will override the .adef setting for all processes in that app:

CPU Share
Fault Action
Groups
Max Core Dump File Bytes
Max File Bytes
Max File Descriptors
Max File System Bytes
Max Locked Memory Bytes
Max Memory Bytes
Max MQueue Bytes
Max Priority
Max Queued Signals
Max Threads
Max Secure Storage Bytes
Pools
Sandboxed
Start
Watchdog Action
Watchdog Timeout

Max Priority

Sets the maximum priority level the app it permitted to use.

Acts as a ceiling only. Lowers the priority level if an app would otherwise be allowed to use a higher priority. It won't raise the priority level for any processes in the app.

Here's a code sample where a process in the app's .adef is configured to start at high priority, and the .sdef section for that app has maxPriority set to medium so the process will start at medium priority.

apps:
{
    foo
    {
        maxPriority: high
    }
}

Another process in the same .adef configured to start at low priority will still start at low priority.

Preloaded

Indicates whether or not an app must be preloaded onto the target device separately from the rest of the system.

The legato AF supports being installed in a read-only partition, mounted as /mnt/legato in the target file system. Writeable files will be kept in another file system mounted as /legato in the target file system.

If the read-only partition must be updated, but there are other (possibly very large) apps in the writeable file system, it may be impossible to deliver an update containing the apps over-the-air at the same time that the read-only partition is updated.

Usually, the read-only partition does not need to be updated, but in some cases, it may be desireable, and this feature can help.

For example, a customer has a giant app containing pictures and audio files. In the factory, the framework and a few apps are loaded into the read-only /mnt/legato, and other apps, including the huge app, are installed in the writeable /legato. Later, when the device is in the field, a change needs to be made to both the modem firmware and the Legato framework, and must be delivered together, as a single FOTA (firmware over the air) update. A new system is built using mksys. But, the resulting system update file is too large to fit in the FOTA update image (and likely very expensive to deliver over the air to hundreds of thousands of devices). Fortunately, the audio files don't need to be updated at the same time, and the audio app can be marked "preloaded" in the .sdef file to exclude it from the system update file. After the FOTA update, the new system will use the audio file that already exists on the target's writeable file system.

apps:
{
    modemService
    audioService
    dataConnectionService
    controller
    userInterface { preloaded: true }
}

If you are not sure whether or not you need this feature, you probably don't. Use of this feature is intended for very specific use cases. It is encouraged that delta updates of systems be used instead, whenever practical.

bindings

Lists IPC bindings that connect apps’ external IPC interfaces. They're listed in the extern section of their .adef files. Each binding connects one client-side interface to one server-side interface.

Interfaces use the app name and the interface name, separated by a period (‘.’). The two bound-together interfaces are separated by an arrow ("->").

For example,

apps:
{
    vavController
    thermostat
    airHandlerProxy
}

bindings:
{
    // Connect the VAV controller to the thermostat
    vavController.temp -> thermostat.temp
    vavController.setpoint -> thermostat.setpoint

    // Connect the VAV controller to the supply air duct temperature sensor
    vavController.ductTemp -> ductTemperatureSensor.temp

    // Hook up the VAV control outputs to the damper actuators.
    vavController.supplyDamper -> supplyAirDamper.damper
    vavController.returnDamper -> returnAirDamper.damper

    // Use a network proxy to request duct temperature changes from the Air Handling Unit.
    vavController.airHandler -> airHandlerProxy.airHandler
}

For security reasons, binding between apps is never performed unless explicitly specified in the .sdef or .adef files.

commands

To make a command-line tool available to a root user who is logged-in to a shell on a target device tty (e.g., through secure shell [ssh] or a serial console):

1. Build an app containing the executable.
2. Add the executable to the "commands:" section of the .sdef file.

Each entry in the commands section looks like this:

commandName = appName:/path/to/exe

The path to the executable must be an absolute path within the application's read-only installed files. For example, if the executable is a script that was bundled into the app "myApp" to appear at "/usr/share/exe" inside the myApp's sandbox at runtime, then the command would be specified as

commandName = myApp:/usr/share/exe

If the executable is built using an "executables" section in a .adef file, then the executable will appear in the app's bin directory. For example,

apps:
{
    myTools // This app's .adef builds an exe called "led" that can be used to turn LEDs on and off.
}

commands:
{
    led = myTools:/bin/led  // When I login via ssh, I can run "led 1 on" to turn on LED 1.
}

Warning

When the command runs, it runs with the full privileges of the user that runs it. So, if you login as root and run a command, the command runs as root.

---

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