Guides

Design Linux PStore and Ramoops modules allow to use memory to pass data from the dying breath of a crashing kernel to its successor. This can be read from Linux after restart, or for hardware using U-Boot directly from the U-Boot command line. PStore PStore is a generic interface to platform dependent persistent storage. Platforms that provide a mechanism to preserve some data across system reboots can register with this driver to provide a generic interface to show records captured in the dying moments. [Read More]

This page describes some general API design principles which are useful to bear in mind when designing APIs (whether those APIs are for C, C++, JavaScript, D-Bus, or something else). Summary API designs must make sense from the point of view of a third-party app developer (start by designing high-level APIs, only add daemons if it is necessary) Interfaces that don’t have to be API should not be API (minimize surface area) Follow GNOME/GObject conventions, so that we get JavaScript bindings automatically Use existing frameworks where we can; if we can’t use them directly, learn from their design Identify privilege boundaries, do not trust less-privileged components, and consider whether some features should be restricted Minimize “surface area” The “SDK API” is intended to remain stable/compatible over time, which means that we are committing to interfaces in the “SDK API” continuing to work in future: third-party code that uses stable Apertis APIs should continue to work in future, without needing changes. [Read More]

Logging debug and informational output from libraries and programs is an open problem, and there are various methods for converting multiple streams of log output into the customary stdout and stderr streams. Below are some suggestions for how to implement logging. However, the most important thing is to ensure that logging is consistent, so that log data can be accessed and searched with a minimum of effort, since that’s what it’s used for. [Read More]

The layout and basic structure of a project’s source directory needs to be done when the project is created. If done well, with thought put into future maintainability and scalability of the build system, little maintenance time will be required on the build system in future. Summary Follow the standard root directory layout so users of the project can find information where they expect. (Root directory layout) Ensure the project and each source code file is clearly licenced. [Read More]

The process for contributing code to Apertis is the same as for many other open source projects: check out the code, make changes locally, then submit them for review and merging. Apertis uses its GitLab instance as a code repository and review tool. This guide assumes good working knowledge of git (see Version control for specific guidelines) and an account with commit rights on GitLab (see Getting commit rights for guidance). [Read More]

Packaging in Apertis is handled through a set of git repositories hosted on GitLab containing the sources for every package. GitLab CI pipelines take care of propagating updates to OBS to build and publish the resulting binaries. For an overview of the broader Apertis workflow see The Apertis Workflow. More detail on the steps required to add and maintain packages can be found in Adding and Updating Components. Repository contents The packaging git repositories follow the DEP-14 Git layout specification. [Read More]

It is often advantageous to be able to test software builds on a target system by booting them over a network, typically booting from artifacts shared via TFTP or NFS. It may not always be viable or sensible to arrange for such resources to be exposed on a shared network. The Apertis SDK can be utilised to provide such services and be configured to share them with a target board with minimal extra infrastructure required. [Read More]

Apertis code, including build scripts, helpers and recipes, is primarily licensed under the Mozilla Public License Version 2.0. Images (such as icons) and documentation in Apertis are licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license. Apertis also makes use of other projects which may have other licenses, such as the GPL and LGPL. For example, this includes projects such as the Linux kernel, WebKit and GLib. [Read More]

The Apertis distribution provides a number of routes for managing updates to deployed devices. This document discusses utilising hawkBit, a domain independent back-end framework for rolling out software updates. Design The hawkBit data model defines a hierarchy of software that starts with a distribution, which can have (sub-)modules and these may have multiple artifacts. The hawkBit Data Model concept can be found here. For Apertis, we want the device agent to be as simple as possible. [Read More]

This document describes how to execute automated LAVA tests controlling resources external to the DUT across a network implementing a LAVA parallel pipeline job. Test Cases The approach proposed in this document will help to address test cases like: Executing a test in the DUT where certain power states are simulated (for example a power loss) during specific test actions using a programmable PSU external to the DUT. Executing a test in the DUT simulating SD card insertion and removal using an external device. [Read More]