From d18c8f66074903392dccb0f1c84017cb36bb02fc Mon Sep 17 00:00:00 2001 From: James Munns Date: Wed, 24 Jun 2026 15:42:51 +0200 Subject: [PATCH 1/2] Add a README to the `app/` folder This readme explains the different kinds of app tomls developers may see. --- app/README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 app/README.md diff --git a/app/README.md b/app/README.md new file mode 100644 index 000000000..d57e9c70a --- /dev/null +++ b/app/README.md @@ -0,0 +1,68 @@ +# Applications + +This folder contains the top level "Application"s of Hubris. By convention, each +subfolder of `app/` are each a "project", and contains: + +* A binary Rust project which serves as the boot-time "entry point", responsible + for hardware initialization, and starting the kernel. +* One or more "app tomls", which serve as configuration for the Hubris build + system. These can either be partial re-usable fragments (the build system + supports multiple-inheritance), or specific end-configurations. + +These "app tomls" contain information such as the tasks that will be built for +the firmware image, as well as information such as pin/interrupt mapping, +RAM/flash range mapping, notifications, and build-time feature enablement. + +Each of the end-configurations will all use the common binary Rust project as +the entry point. It is common to have one end-configuration "app toml" for each +hardware board revision, or different modes of operation of that hardware, +described more below. + +## "App Toml" conventions + +The following are informal conventions currently followed by the Hubris project. +These are "informal" because they are not special-cased in the Hubris build +system. + +### `base.toml` + +Often, the majority of configuration for a given project is common across all +hardware revisions and modes of operation. In this case, the maximal common +set of configuration is done in a `base.toml`, to avoid needing to update +multiple app tomls when a setting is changed. + +This `base.toml` will then be inherited by all of the other end-configurations. + +### `-dev` suffix + +`-dev` end-configurations are typically used during DEVelopment. They often +enable debugging interfaces or options that are not enabled in production +releases. + +These options may be rolled into a `dev.toml` that is inherited by more +specific end-configuration app tomls. + +### `-lab` suffix + +`-lab` end-configurations are used in "benchtop" hardware testing. They +typically also inherit any `-dev` configuration settings. The largest +distinction here is that `-lab` end-configurations will not automatically +perform startup power sequencing steps done by other images. + +These options may be rolled into a `lab.toml` that is inherited by more +specific end-configuration app tomls. + +### `-bu` suffix + +`-bu` end-configurations are for "BringUp". This convention is not widely used +anymore. + +### `-standalone` suffix + +`-standalone` end-configurations are used when a Hubris-based system is expected +to operate without the major component it is built to support. An example of +this is the `grapefruit` project, which may operate without the `ruby` +development board featuring the AMD processor. + +In this configuration, pin mapping may be changes to allow greater access to +I/O ports for testing and verification activities. From 0aaaf6f0005640804289cf75c999b3387a88b8ba Mon Sep 17 00:00:00 2001 From: James Munns Date: Fri, 26 Jun 2026 13:42:05 +0200 Subject: [PATCH 2/2] Move from "app toml" to "manifest" as the preferred term --- app/README.md | 55 ++++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/app/README.md b/app/README.md index d57e9c70a..07f9f00ac 100644 --- a/app/README.md +++ b/app/README.md @@ -1,24 +1,27 @@ # Applications This folder contains the top level "Application"s of Hubris. By convention, each -subfolder of `app/` are each a "project", and contains: +subfolder of `app/` is a "project", and contains: * A binary Rust project which serves as the boot-time "entry point", responsible for hardware initialization, and starting the kernel. -* One or more "app tomls", which serve as configuration for the Hubris build - system. These can either be partial re-usable fragments (the build system - supports multiple-inheritance), or specific end-configurations. - -These "app tomls" contain information such as the tasks that will be built for +* One or more `.toml` files, which serve as configuration for the Hubris build + system. These can either be partial re-usable fragments, or complete + end-configurations, known as "manifests". +* For manifests composed of multiple fragments, the build system is responsible + for combining the top-level TOML file and any inherited fragments into a + single combined manifest document, which is shipped with the Hubris archive. + +These TOML files contain information such as the tasks that will be built for the firmware image, as well as information such as pin/interrupt mapping, RAM/flash range mapping, notifications, and build-time feature enablement. Each of the end-configurations will all use the common binary Rust project as -the entry point. It is common to have one end-configuration "app toml" for each -hardware board revision, or different modes of operation of that hardware, -described more below. +the entry point. It is common to have one manifest for each hardware board +revision, or different modes of operation of that hardware, described more +below. -## "App Toml" conventions +## `.toml` file naming conventions The following are informal conventions currently followed by the Hubris project. These are "informal" because they are not special-cased in the Hubris build @@ -29,38 +32,36 @@ system. Often, the majority of configuration for a given project is common across all hardware revisions and modes of operation. In this case, the maximal common set of configuration is done in a `base.toml`, to avoid needing to update -multiple app tomls when a setting is changed. +multiple manifests when a setting is changed. -This `base.toml` will then be inherited by all of the other end-configurations. +This `base.toml` fragment will then be inherited by all of the other manifests. ### `-dev` suffix -`-dev` end-configurations are typically used during DEVelopment. They often -enable debugging interfaces or options that are not enabled in production -releases. +`-dev` manifests are typically used during DEVelopment. They often enable +debugging interfaces or options that are not enabled in production releases. -These options may be rolled into a `dev.toml` that is inherited by more -specific end-configuration app tomls. +These options may be rolled into a `dev.toml` fragment that is inherited by more +specific `*-dev.toml` manifests. ### `-lab` suffix -`-lab` end-configurations are used in "benchtop" hardware testing. They -typically also inherit any `-dev` configuration settings. The largest -distinction here is that `-lab` end-configurations will not automatically -perform startup power sequencing steps done by other images. +`-lab` manifests are used in "benchtop" hardware testing. They typically also +inherit any `-dev` configuration settings. The largest distinction here is that +`-lab` manifests will not automatically perform startup power sequencing steps +done by other firmware images. -These options may be rolled into a `lab.toml` that is inherited by more -specific end-configuration app tomls. +These options may be rolled into a `lab.toml` fragment that is inherited by more +specific `*-lab.toml` manifests. ### `-bu` suffix -`-bu` end-configurations are for "BringUp". This convention is not widely used -anymore. +`-bu` manifests are for "BringUp". This convention is not widely used anymore. ### `-standalone` suffix -`-standalone` end-configurations are used when a Hubris-based system is expected -to operate without the major component it is built to support. An example of +`-standalone` manifests are used when a Hubris-based system is expected +to operate without a major component it is designed to support. An example of this is the `grapefruit` project, which may operate without the `ruby` development board featuring the AMD processor.