Skip to content

Topology

Jump to bottom
Tristan Israël edited this page Jul 16, 2026 · 12 revisions

This page describes the topology principles in Safecor.

The topology works like an infra-as-code mechanism: it delegates (part of) the definition of the system technical characteristics to the developer of the product.

In Safecor, the topology definition allows to:

  • declare the product name and other information,
  • enable/disable the USB bus,
  • enable/disable the graphics,
  • blacklist PCI devices,
  • define a package to install for the Graphical User Interface (GUI),
  • define the memory allocated to the GUI,
  • rotate the screen,
  • define the CPU allocation to the Domains,
  • declare business Domains, their memory and package to install to,
  • define configurations to match specific hardware.

This is a typical topology.json:

{
    "usb": {
        "use": 1
    },
    "pci": {
        "blacklist": [ "00:0d.0" ]
    },
    "screen": {
        "enabled": 1,
        "rotation": 90,
        "default_focus": "myapp-gui"
    },    
    "vcpu": {
        "groups": {
            "group1": 0.8
        }
    },
    "business": {
        "domains": [
            {
                "name": "myapp-gui",
                "app-package": "myapp-gui",
                "memory": 4096,
                "vcpu_group": "group1",
                "temp_disk_size": 4096,
                "swap_size": 4096,
                "has_gui": 1
            },
            {
                "name": "myapp-function2",
                "app-package": "myapp-function2",
                "memory": 4096,
                "vcpu_group": "group1"
            }
        ]
    },
    "storage": {
        "type": "disk",
        "index": 1,
        "size": -1
    },
    "product": {
        "name": "Safecor",
        "splash_bgcolor": "#1ca9f7",
        "languages": [ "en", "fr" ],
        "default_language": "en"
    }

}

Sections

Here is the detail of each settings section.

usb

The usb section defines the settings for the USB functions of the system.

Key Type Description
use int Set to 1 if the Domain sys-usb should be setup and used, else 0.

screen

The screen section defines the settings for the monitors.

Key Type Description
enable int Set to 1 if the system includes any GUI.
rotation int Defines the rotation of the screen if needed, for example on a tablet. Accepted valued are: 0, 90, 180 or 270.
default_focus string Defines the graphical Domain that has the focus on boot. It will receive the inputs exclusively.

storage

The storage section defines the settings for the local storage.

Key Type Description
type str Set it to disk to enable the creation of an encrypted storage file on the disk
index   int If the system embeds multiple disks, this is the index of the disk to use for the storage (starting at 1)
size int The size of the storage in MB. Set it to -1 to use all available space.

business

The business section defines the settings for the business components of the system, including the Domains.

Key Type Description
domains  array This sections defines the domains which will be created on startup.
domains..name string Gives a name to the Domain.
domains..package string Defines the package (APK) which will be installed in the Domain.
domains..memory int Defines the memory, in MB, which whould be allocated to the Domain.
domains..temp_disk int If defined, a disk will be created with size in MB and mounted in the Domain on /tmp
domains..swap_size int If defined, a swap disk will be created with size in MB
domains..has_gui int If defined, the Domain will produce graphical content. gui.use should also be enabled in this case.

product

The product section defines the settings for the definition of the product and global settings.

Key Type Description
name string The name of the product
splash_bgcolor The color that will be added in the background of the boot logo
languages The list of languages handled by the product, including the business components
default_language The default language that will be used by the system

Resource management

This sections explains how resources can be distributed into the system.

Resources (CPU, memory) can be affected to Domains (sys-gui and business Domains) as portions of the platform resources.

vCPU management

The following rules apply:

  • the Dom0 and sys-usb Domains can't be configured.
    • Dom0 will have the 2 first vCPUs unless the system has less than 4, so he gets only the first.
    • sys-usb will have the same vCPUs as Dom0
  • the configurable groups are:
    • sys-gui will have the 2 next vCPUs by default unless the system has less than 4, so he gets only the second one. This value can be modified in topology.json.
    • the rest can be divided in groups and affected to the Domains.

The proportions are:

  • 15% to Dom0/sys-usb (shared) -> minimum value is 1
  • 75% for the rest of the system:
    • 20% to sys-gui by default (overridable)
    • 80% to the business Domains divisible into groups.

Groups of vCPUs are declared in the section vcpu.groups which represents 100% of the allocatable vCPUs (75% of the system).

Then each business domain can have a group allocated using the keyword vcpu_group.

Example :

"vcpu": {
    "groups": {
        "my_group": 0.8
    }
} 

"business": {
    "domains": [
        {
            "name": "myapp-function1",            
            "vcpu_group": "my_group"
        }
    ]
}

See also

Clone this wiki locally