diff --git a/content/designs/application-bundle-metadata.md b/content/designs/application-bundle-metadata.md
index b4809e277a563469adfd78023256e10dc6673c59..23e91396e25695ac070a1df0b90a96150b8cd545 100644
--- a/content/designs/application-bundle-metadata.md
+++ b/content/designs/application-bundle-metadata.md
@@ -62,7 +62,7 @@ UX design, app-modal and system-modal dialogs might be treated as
visually similar to notifications; if they are, the compositor author
might also wish to assign priorities from the same ranges to dialogs.
-Similar to the [][Audio management priorities] use case, app-bundles that
+Similar to the [Audio management priorities]( {{< ref "#audio-management-priorities" >}} ) use case, app-bundles that
have a legitimate reason for their notifications or dialogs to be
high-priority must be able to achieve this, but malicious app-bundles
whose authors aim to misuse this facility must not be able to achieve
@@ -172,7 +172,7 @@ It must be straightforward for an app-store curator to inspect the
metadata that is present in an app-bundle, for example so that they can
refuse to publish app-bundles that ask for audio or notification priorities
that they have no legitimate reason to use, or for which the name,
-icon or other information used for [][App-bundle labelling] is misleading.
+icon or other information used for [App-bundle labelling]( {{< ref "#app-bundle-labelling" >}} ) is misleading.
### Store app-bundle confidentiality
@@ -291,7 +291,7 @@ use of [`.desktop` files][Desktop Entry Specification] for
The AppStream specification refers to *components*, which are a
generalization of the same concept as Apertis app-bundles, and can
include software from various sources, including traditional distribution
-packages and bundling technologies such as [][Flatpak].
+packages and bundling technologies such as [Flatpak]( {{< ref "#flatpak" >}} ).
#### Flatpak
@@ -360,7 +360,7 @@ file into `/Applications/${bundle_id}/share/metainfo/${bundle_id}.appdata.xml`
or `/Applications/${bundle_id}/share/metainfo/${bundle_id}.metainfo.xml`
(depending on whether it has entry points), with contents
corresponding to those specified for built-in app bundles.
-For [][Store app-bundle confidentiality], a store app-bundle's
+For [Store app-bundle confidentiality]( {{< ref "#store-app-bundle-confidentiality" >}} ), a store app-bundle's
AppArmor profile must not allow it to read the contents of a different
store app-bundle, and in particular its AppStream metadata.
@@ -371,7 +371,7 @@ the `share/appdata/` directory to be processed for application bundles.
Since existing application bundles do not contain it, this does not create
a compatibility problem.
-For [][App-store curator oversight], if the implementation reads
+For [App-store curator oversight]( {{< ref "#app-store-curator-oversight" >}} ), if the implementation reads
other sources of
metadata from a store app-bundle (for example the `.desktop` entry points
provided by the app-bundle), then the implementation must document those
@@ -387,7 +387,7 @@ These cache files should be monitored by the
[libcanterbury-platform][Canterbury] library, using the standard
`inotify` mechanism. Any cache files that contain store app-bundles must
not be readable by a store app-bundle, to preserve
-[][Store app-bundle confidentiality].
+ [Store app-bundle confidentiality]( {{< ref "#store-app-bundle-confidentiality" >}} ).
The other APIs that are required are straightforward to implement in the
[libcanterbury-platform][Canterbury] library by reading from the cache files.
@@ -429,7 +429,7 @@ separate cache files, for several reasons:
Any metadata keys and values that have not been standardized by the AppStream
project (for example audio roles that might be used to determine a bundle's
-audio priority) must be represented using [][Extension points] within the
+audio priority) must be represented using [Extension points]( {{< ref "#extension-points" >}} ) within the
AppStream metadata. The formal [AppStream specification][AppStream] does
not provide an extension point, but the
[reference implementation][libappstream]
@@ -520,7 +520,7 @@ What are our preferred sizes?
#### Future directions
Platform components that are not part of an app-bundle do not have bundle IDs.
-We anticipate that [][Platform component metadata] might be identified by
+We anticipate that [Platform component metadata]( {{< ref "#platform-component-metadata" >}} ) might be identified by
a separate identifier in the same reversed-DNS namespace, and that the
consumer of requests might derive the platform component identifier by
looking for components that declare metadata fields matching the
@@ -528,24 +528,24 @@ requester's AppArmor label (part of the AppArmor context).
## Summary
-* [][app-bundle metadata] is read from the cache that summarizes
+* [app-bundle metadata]( {{< ref "#app-bundle-metadata" >}} ) is read from the cache that summarizes
built-in and store app-bundles. The [libcanterbury-platform][Canterbury]
library provides the required APIs; in particular, change notification
can be done using `inotify`.
-* [][Secure identification] is provided by
+* [Secure identification]( {{< ref "#secure-identification" >}} ) is provided by
[parsing the requesting process's AppArmor
context][Secure identification design].
-* The [][Audio stream and notification requirements]
+* The [Audio stream and notification requirements]( {{< ref "#audio-stream-and-notification-requirements" >}} )
are addressed by providing their desired metadata in the app-bundle
metadata, in the form of arbitrary key/value pairs.
-* [][App-store curator oversight] is facilitated by documenting all
+* [App-store curator oversight]( {{< ref "#app-store-curator-oversight" >}} ) is facilitated by documenting all
of the sources within a store app-bundle from which the implementation
gathers metadata to populate its cache.
-* [][Store app-bundle confidentiality] is provided by storing the cache
+* [Store app-bundle confidentiality]( {{< ref "#store-app-bundle-confidentiality" >}} ) is provided by storing the cache
file describing installed store app-bundles in a location where store
app-bundles cannot read it, and by avoiding the need to introduce a
D-Bus service from which they could obtain the same information.
-* The [appstream-glib] library supports [][Extension points] in
+* The [appstream-glib] library supports [Extension points]( {{< ref "#extension-points" >}} ) in
AppStream XML.
<!-- External references -->
diff --git a/content/designs/application-entry-points.md b/content/designs/application-entry-points.md
index d84ce41da49964dba3dad4060dfdb851d5d6a702..f8b6cc583a95622f68b6d93a9ff9ae591a09eba8 100644
--- a/content/designs/application-entry-points.md
+++ b/content/designs/application-entry-points.md
@@ -217,7 +217,7 @@ The following additional keys are defined in the `[Desktop Entry]` group.
* `X-Apertis-ParentEntry` (string): For situations where multiple
menu entries start the same program in different modes, all but one
of those menu entries set `X-Apertis-ParentEntry` to the entry point ID of
- the remaining menu entry. See [][Multiple-view applications] and
+ the remaining menu entry. See [Multiple-view applications]( {{< ref "#multiple-view-applications" >}} ) and
the [D-Bus Activation][Bundle spec D-Bus activation] section of the
Apertis Application Bundle Specification.
diff --git a/content/designs/application-framework.md b/content/designs/application-framework.md
index 2fdceebd8383d0f81852c1e7611e8be936edbf73..6bc3574074a7193788e026bbaac9c9e744227481 100644
--- a/content/designs/application-framework.md
+++ b/content/designs/application-framework.md
@@ -112,7 +112,7 @@ a [wide set of options to further secure
services](https://gist.github.com/ageis/f5595e59b1cddb1513d1b425a323db04), track
their resource consumption, ensure their availability, etc.
-
+
## Application runtime: Flatpak
@@ -561,7 +561,7 @@ framework being shipped on the reference images in the short term.
As the new application framework matures, components will get swapped on the
reference images, leaving the legacy components available in the archive.
-See the [](canterbury-legacy-application-framework.md) for more details.
+See the[canterbury legacy application framework]( {{< ref "canterbury-legacy-application-framework.md" >}} ) for more details.
# High level implementation plan for the next-generation Apertis application framework
@@ -578,7 +578,7 @@ The implementation will be held whithin a few different axis that can be
developed in parallel and in the order that might make more sense at the time
of the implementation.
-
+
## Flatpak on the Apertis images
The goal here is to ensure that all the Flatpak tools and services are working on
diff --git a/content/designs/application-layout.md b/content/designs/application-layout.md
index c3e182f03a1d6e56439122a98b6146d48d617476..da5fa9ad615f9b96be2513af4df6e02970affab3 100644
--- a/content/designs/application-layout.md
+++ b/content/designs/application-layout.md
@@ -14,8 +14,7 @@ to be able to restrict each of those categories of storage to a known
directory.
This document is intended to update and partially supersede
-discussions of storage locations in the [](applications.md) and
-[](system-updates-and-rollback.md) design documents.
+discussions of storage locations in the[applications]( {{< ref "applications.md" >}} ) and[system updates and rollback]( {{< ref "system-updates-and-rollback.md" >}} ) design documents.
The [Apertis Application Bundle Specification] describes the files
that can appear in an application bundle and are expected to
@@ -164,7 +163,7 @@ SQLite database.
during a rollback. ([System Update and Rollback design] §6.3, "Update
and Rollback Procedure")
-* **Unresolved:** [][Are downloads rolled back?]
+* **Unresolved:** [Are downloads rolled back?]( {{< ref "#are-downloads-rolled-back" >}} )
#### Built-in applications
@@ -192,7 +191,7 @@ containing Browser version 18.
same practical result as if an equivalent store application bundle had
been uninstalled and immediately reinstalled.
* Cache files for built-in applications are treated the same as cache
- files for [][Store applications], above.
+ files for [Store applications]( {{< ref "#store-applications" >}} ), above.
#### Global operations
@@ -208,7 +207,7 @@ A "data reset" operation affects the entire system. It clears everything.
application bundle. It should delete all variable data in each application
bundle, and all variable data that is shared by application bundles.
-**Unresolved:** [][Does data reset uninstall apps?]
+**Unresolved:** [Does data reset uninstall apps?]( {{< ref "#does-data-reset-uninstall-apps" >}} )
### System extensions
@@ -255,8 +254,8 @@ system extensions*, analogous to the *public interfaces* defined by the
units, D-Bus services, icons etc. provided by store application bundles. A
permission flag could be provided to make an exception to this rule, for
example for an application-launcher application like Android's Trebuchet.
- * **Unresolved:** [][Are inactive themes visible to all?]
-* **Unresolved:** [][Are built-in bundles visible to all?]
+ * **Unresolved:** [Are inactive themes visible to all?]( {{< ref "#are-inactive-themes-visible-to-all" >}} )
+* **Unresolved:** [Are built-in bundles visible to all?]( {{< ref "#are-built-in-bundles-visible-to-all" >}} )
### Miscellaneous
@@ -283,8 +282,8 @@ system extensions*, analogous to the *public interfaces* defined by the
The overall structure of these recommendations is believed to be valid,
but the exact paths used may be subject to change, depending on the
-answers to the [][Unresolved design questions] and comparison with
-containerization technologies such as [][Flatpak].
+answers to the [Unresolved design questions]( {{< ref "#unresolved-design-questions" >}} ) and comparison with
+containerization technologies such as [Flatpak]( {{< ref "#flatpak" >}} ).
### Writing application bundles
@@ -381,7 +380,7 @@ themes. Similar to the application icon, the browser may install variants
of that icon for themes other than `hicolor`, if its author is aware of
particular themes and intends the icon to coordinate with those themes.
-**Unresolved:** [][Standard icon sizes?]
+**Unresolved:** [Standard icon sizes?]( {{< ref "#standard-icon-sizes" >}} )
#### Per-user, per-bundle data
@@ -418,7 +417,7 @@ download service, Newport, may also write to this location. Uninstalling
the application bundle or removing the user account causes the download
directory to be deleted.
-**Unresolved:** [][Are downloads rolled back?]
+**Unresolved:** [Are downloads rolled back?]( {{< ref "#are-downloads-rolled-back" >}} )
#### Per-user, bundle-independent data
@@ -439,9 +438,9 @@ cleared or removed by uninstalling an app-bundle. They are cleared when
the user account is deleted, or when a data-reset is performed on the
entire device.
-**Unresolved:** [][How do bundles discover the per-user, bundle-independent location?]
+**Unresolved:** [How do bundles discover the per-user, bundle-independent location?]( {{< ref "#how-do-bundles-discover-the-per-user-bundle-independent-location" >}} )
-**Unresolved:** [][Is `g_get_home_dir()` bundle-independent?]
+**Unresolved:** [Is `g_get_home_dir()` bundle-independent?]( {{< ref "#is-g_get_home_dir-bundle-independent" >}} )
#### User-independent, per-bundle data
@@ -480,9 +479,9 @@ cleared by a data reset.
#### Other well-known directories
-**Unresolved:** [][Is `PICTURES` per-user?]
+**Unresolved:** [Is `PICTURES` per-user?]( {{< ref "#is-pictures-per-user" >}} )
-**Unresolved:** [][What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]
+**Unresolved:** [What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]( {{< ref "#what-is-the-scope-of-desktop-documents-templates" >}} )
### Implementation
@@ -548,7 +547,7 @@ links for the following system integration files:
Store applications must not contain these links:
similar links are created at install-time instead. See
-[][Store application system integration links] for details.
+ [Store application system integration links]( {{< ref "#store-application-system-integration-links" >}} ) for details.
#### Special directory configuration
@@ -559,7 +558,7 @@ variables, so that they automatically use appropriate directories:
`g_get_user_data_dir`)
* `XDG_DATA_DIRS=/Applications/$bundle_id/share:/var/lib/apertis_extensions/public:/usr/share`
(used by `g_get_system_data_dirs`)
- * See [][Store application system integration links] for the
+ * See [Store application system integration links]( {{< ref "#store-application-system-integration-links" >}} ) for the
rationale for `/var/lib/apertis_extensions/public`
* `XDG_CONFIG_HOME=/var/Applications/$bundle_id/users/$uid/config`
(used by `g_get_user_config_dir`)
@@ -572,7 +571,7 @@ variables, so that they automatically use appropriate directories:
* `XDG_RUNTIME_DIR=/run/user/$uid` (used by `g_get_user_runtime_dir`
and provided automatically by systemd; access is subject to a "whitelist")
-**Unresolved:** [][Should `LD_LIBRARY_PATH` be set?]
+**Unresolved:** [Should `LD_LIBRARY_PATH` be set?]( {{< ref "#should-ld_library_path-be-set" >}} )
This is automatically done by `canterbury-exec` in Apertis 16.06 or later,
unless the entry point's bundle ID cannot be determined from its `.desktop`
@@ -583,25 +582,25 @@ be prevented in future.
Built-in application bundles should be given the same environment
variables, but with `/usr/Applications` replacing `/Applications`.
-**Unresolved:** [][Is `g_get_home_dir()` bundle-independent?]
+**Unresolved:** [Is `g_get_home_dir()` bundle-independent?]( {{< ref "#is-g_get_home_dir-bundle-independent" >}} )
-**Unresolved:** [][Is `g_get_temp_dir()` bundle-independent?]
+**Unresolved:** [Is `g_get_temp_dir()` bundle-independent?]( {{< ref "#is-g_get_temp_dir-bundle-independent" >}} )
In addition, the XDG special directories should be configured as follows
for both built-in and store application bundles:
* `g_get_user_special_dir (G_USER_DIRECTORY_DESKTOP)`: **Unresolved**:
- [][What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]
+ [What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]( {{< ref "#what-is-the-scope-of-desktop-documents-templates" >}} )
* `g_get_user_special_dir (G_USER_DIRECTORY_DOCUMENTS)`: **Unresolved**:
- [][What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]
+ [What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]( {{< ref "#what-is-the-scope-of-desktop-documents-templates" >}} )
* `g_get_user_special_dir (G_USER_DIRECTORY_DOWNLOAD)`:
`/var/Applications/$bundle_id/users/$uid/downloads`
* `g_get_user_special_dir (G_USER_DIRECTORY_MUSIC)`: `/home/shared/Music`
* `g_get_user_special_dir (G_USER_DIRECTORY_PICTURES)`: **Unresolved**:
- [][Is `PICTURES` per-user?]
+ [Is `PICTURES` per-user?]( {{< ref "#is-pictures-per-user" >}} )
* `g_get_user_special_dir (G_USER_DIRECTORY_PUBLIC_SHARE)`: `/home/shared`
* `g_get_user_special_dir (G_USER_DIRECTORY_TEMPLATES)`: **Unresolved**:
- [][What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]
+ [What is the scope of `DESKTOP`, `DOCUMENTS`, `TEMPLATES`?]( {{< ref "#what-is-the-scope-of-desktop-documents-templates" >}} )
* `g_get_user_special_dir (G_USER_DIRECTORY_VIDEOS)`:
`/home/shared/Videos`
@@ -623,7 +622,7 @@ If they exist, `/var/Applications/$bundle_id/{config,data,cache}/` are
owned by root, with permissions `a=rwx`. If they are not required and
allowed by a permissions flag, they must not exist.
-**Unresolved**: [][Can we prevent symlink attacks in shared directories?]
+**Unresolved**: [Can we prevent symlink attacks in shared directories?]( {{< ref "#can-we-prevent-symlink-attacks-in-shared-directories" >}} )
`/var/Applications/$bundle_id/users/$uid/` and all of its subdirectories
are owned by `$uid`, with permissions `u=rwx,og-rwx` for privacy (in
@@ -748,7 +747,7 @@ was implemented in Apertis 16.06.
Application installation for store applications may
set up symbolic links in `/var/lib/apertis_extensions`
for the categories of system integration files described in
-[][System integration links for built-in applications], but the files and
+ [System integration links for built-in applications]( {{< ref "#system-integration-links-for-built-in-applications" >}} ), but the files and
their contents must be [restricted][App Store Approval] unless the bundle
has special permissions flags. In particular, all entry points (agents
and applications) in a bundle must be in the relevant [ISV]'s namespace.
@@ -882,7 +881,7 @@ Suppose the system-wide theme is "blue", and the user has installed but
not activated "red" and "green" themes from the app store. Is it OK for
an unprivileged app-bundle to be able to see that the "red" and "green"
themes exist?
-* The same applies to any other [][Public system extensions].
+* The same applies to any other [Public system extensions]( {{< ref "#public-system-extensions" >}} ).
* For simplicity, we recommend the answer "yes, this is acceptable"
unless there is a reason to do otherwise.
@@ -1021,8 +1020,8 @@ If we install, upgrade or remove the store bundle `com.example.MyApp`,
which additionally has some variable files that are shared between
users. With the recommended design, we only have to perform O(1)
subvolume operations (two with the recommended design, one if we
-[][Merge static and variable files for store applications], or three
-if we [][Add a third subvolume per app-bundle for cache]). In this
+ [Merge static and variable files for store applications]( {{< ref "#merge-static-and-variable-files-for-store-applications" >}} ), or three
+if we [Add a third subvolume per app-bundle for cache]( {{< ref "#add-a-third-subvolume-per-app-bundle-for-cache" >}} )). In this
alternative design, we would have to perform O(number of users) subvolume
operations, in this case 7: one for the bundle's static files, one for
its variable files shared between users, and one per user.
@@ -1052,8 +1051,8 @@ the recommended design would require at least 30 subvolume deletions
It would be technically possible to install user-services (services that
run as a particular user, similar to Tracker) in an application bundle,
and register them with the wider system via system integration links
-([][System integration links for built-in applications],
-[][Store application system integration links])
+( [System integration links for built-in applications]( {{< ref "#system-integration-links-for-built-in-applications" >}} ),
+ [Store application system integration links]( {{< ref "#store-application-system-integration-links" >}} ))
pointing to their systemd user services and D-Bus session services.
We recommend that this is not done, because general systemd user
diff --git a/content/designs/applications.md b/content/designs/applications.md
index e0c830b04939e8c22adb8c283032654520e43682..2dd9cf14843d5dcf0abb68f0a4e6b7296a8d5cf5 100644
--- a/content/designs/applications.md
+++ b/content/designs/applications.md
@@ -26,28 +26,28 @@ application.
To avoid ambiguity, this document will avoid using “application†as a
jargon term. Instead, we use two distinct terms for separate concepts
that could informally be referred to as applications: *graphical
-programs*, and *application bundles*. See [][Terminology].
+programs*, and *application bundles*. See [Terminology]( {{< ref "#terminology" >}} ).
-Apertis is a multiuser system; see the [](multiuser.md) design document for
+Apertis is a multiuser system; see the[multiuser]( {{< ref "multiuser.md" >}} ) design document for
more on the specifics of the multiuser experience and the division of
responsibilities between middleware and HMI elements.
Apertis has first shipped with a custom application framework to address the
-needs described in this document, see [](canterbury-legacy-application-framework.md).
+needs described in this document, see[canterbury legacy application framework]( {{< ref "canterbury-legacy-application-framework.md" >}} ).
The custom legacy framework is in the process of being replaced with an
-evolution based upstream components, see [](application-framework.md).
+evolution based upstream components, see[application framework]( {{< ref "application-framework.md" >}} ).
## Traditional package managers are unfit for applications
Apertis relies heaviliy on a traditional packaging system to compose
the base OS. However, it does not rely on it to distribute the composed
system as it is not a good fit for the use-cases Apertis addresses,
-see [](system-updates-and-rollback.md) for more details.
+see[system updates and rollback]( {{< ref "system-updates-and-rollback.md" >}} ) for more details.
Similarly, a traditional packaging system is not a good fit for applications in
Apertis since:
- Apertis relies on a immutable base OS to implement a robust update
- mechanism, see [](system-updates-and-rollback.md) for more details.
+ mechanism, see[system updates and rollback]( {{< ref "system-updates-and-rollback.md" >}} ) for more details.
This means that a traditional package manager is not used to distribute
updates on the field and that the writable application storage should
be kept separate from the read-only base OS.
@@ -88,7 +88,7 @@ that term in this document.
### Store account
-The [][Digital rights management] section discusses ***store accounts***,
+The [Digital rights management]( {{< ref "#digital-rights-management" >}} ) section discusses ***store accounts***,
anticipated to have a role analogous to Google Play accounts on Android
or Apple Store accounts on iOS. If these accounts exist, we recommend
against using the term “user†for them, since that would be easily
@@ -103,7 +103,7 @@ The software in a Apertis device can be divided into three categories:
bundles*. Of these categories, some store application bundles may be
*preinstalled*.
-
+
The ***platform*** is comprised of all the facilities used to boot up
the device and perform basic system checks and restorations. It also
@@ -206,7 +206,7 @@ decide on based on what makes more sense for the application.
The application store will be responsible for packaging a developer's
store application bundle into a bundle file along with a “store
-directoryâ€(see [][Store directory]) that contains some generated
+directoryâ€(see [Store directory]( {{< ref "#store-directory" >}} )) that contains some generated
metadata and a signature. Special “SDK†system images will provide
software development tools and allow the installation of unsigned
packages, but the normal “target†system image will not allow the
@@ -345,7 +345,7 @@ used by [Flatpak for its application identifiers](http://docs.flatpak.org/en/lat
AppArmor profile is deterministically derived from the bundle ID, by
being exactly `/Applications/${bundle_id}/**` where `${bundle_id}`
represents the bundle ID.
- (See [][AppArmor profiles] for rationale for this choice.)
+ (See [AppArmor profiles]( {{< ref "#apparmor-profiles" >}} ) for rationale for this choice.)
For instance, all programs in the
`org.apertis.Frampton` built-in app-bundle would run under a profile
@@ -409,7 +409,7 @@ the following steps:
- Generate an AppArmor profile for the application based on its
[permissions]
- - Generate the application's [][Store directory].
+ - Generate the application's [Store directory]( {{< ref "#store-directory" >}} ).
- Make the application available at the store.
@@ -478,7 +478,7 @@ The installation could be locked in the following ways:
person, as represented by their store account - presumably a store
account must be present and logged in for this to work. The store
account is assumed to be analogous to an Apple Store or Google Play
- account: as noted in [][Terminology], we recommend
+ account: as noted in [Terminology]( {{< ref "#terminology" >}} ), we recommend
avoiding the term “user†here, since a store account does not
necessarily correspond 1:1 to the “users†discussed in the Multiuser
design document.
@@ -581,7 +581,7 @@ as a separate service process, rather than merely a library that is
loaded by the application program.
Some permissions may prove to be more of an annoyance than helpful to
-the user. For example, if [][Start] are employed by vast numbers
+the user. For example, if [Start]( {{< ref "#start" >}} ) are employed by vast numbers
of applications, users may not wish to be informed every time a new
application requires one. It may be worth considering having some
permission acceptance governed by system settings, and only directly
@@ -592,7 +592,7 @@ query the user if a permission is “important†(such as sending SMS).
Applications will have access to several types of writable
application storage.
Care should be taken to select the appropriate area as different areas
-are handled differently if rollbacks (See [][Roll-back]) occur. The
+are handled differently if rollbacks (See [Roll-back]( {{< ref "#roll-back" >}} )) occur. The
storage types are:
- Application User – for settings and any other per-user files. In the
@@ -616,7 +616,7 @@ storage types are:
Apertis space may be limited, and since it is thought that users
will usually want to share media between accounts, the data in this
storage area will be accessible by all users. More details on this
- are available in the [](multiuser.md) design.
+ are available in the[multiuser]( {{< ref "multiuser.md" >}} ) design.
The [XDG Base Directory Specification] environment variables will
guide applications to find the appropriate locations for the different
@@ -667,7 +667,7 @@ another computer and potentially copy and distribute applications.
The device could be recognized by its label as reported
by the blkid command, and added to the startup application scan in
-[][Boot time procedures].
+ [Boot time procedures]( {{< ref "#boot-time-procedures" >}} ).
If this is extended to multiple SD cards, difficulties arise in deciding
which storage device to install an application to. Either configuration
@@ -710,7 +710,7 @@ depends on.
An application bundle may provide back-ends to existing system
functionality and add new features to installed software without
necessarily adding any new applications to the application manager.
-These are called “system extensions†and are detailed in [][System extensions].
+These are called “system extensions†and are detailed in [System extensions]( {{< ref "#system-extensions" >}} ).
### Store Applications
@@ -727,7 +727,7 @@ completed application download if the connection is broken or Apertis is
shut down before the download completes.
A background download service will be provided by Apertis (See
-[][Reliable download service]). This service will continue downloads if they
+ [Reliable download service]( {{< ref "#reliable-download-service" >}} )). This service will continue downloads if they
are interrupted or if the system is restarted. When the download is
completed, or if the download is incapable of being completed, a
callback will be made to the requester via D-Bus.
@@ -942,11 +942,11 @@ upgrade begins, and switch back after the upgrade finishes.
Apart from any extension type specific steps performed by the
application manager, the upgrade process will be exactly as described in
-[][Upgrades].
+ [Upgrades]( {{< ref "#upgrades" >}} ).
#### Removal
-Once again, the process only deviates from [][Removal] by
+Once again, the process only deviates from [Removal]( {{< ref "#removal" >}} ) by
performing any specific actions required by the extension type before
following the standard procedure.
@@ -1072,7 +1072,7 @@ We refer to the programs that are launched in these ways as *entry points*.
Collabora feels that the first three types of launch should be under the
control of the application manager. See
-[][Responsibilities of the application manager]
+ [Responsibilities of the application manager]( {{< ref "#responsibilities-of-the-application-manager" >}} )
Another method of launching processes is present – D-Bus activation. If
a D-Bus client attempts to use a known-name for a service that isn't
@@ -1150,7 +1150,7 @@ It should be noted that state saving is difficult to implement, and much
of the work is the responsibility of the application writer. While
Apertis can provide functions for handling the incoming signal and
storing state data (See
-[][State saving convenience APIs]), the
+ [State saving convenience APIs]( {{< ref "#state-saving-convenience-apis" >}} )), the
hardest part is determining exactly what application state needs to be
saved in order for the application to exit and restart in exactly the
same way it had been previously running.
diff --git a/content/designs/audio-management.md b/content/designs/audio-management.md
index cda06f4a74eaf76ff54bf24af5cf305ae9a20ce9..9ced45333e47c495772735785b06d2beeacacf03 100644
--- a/content/designs/audio-management.md
+++ b/content/designs/audio-management.md
@@ -280,14 +280,14 @@ running a distinct instance of the Apertis CE domain.
### Standalone operation
The audio manager must support standalone operation, in which it accesses audio
-hardware directly ([][Application developer]).
+hardware directly ( [Application developer]( {{< ref "#application-developer" >}} )).
### Integrated operation
The audio manager must support integrated operation, in which it cannot access
the audio hardware directly, but must instead send requests and audio streams
-to the hybrid system. ([][Different types of sources],
-[][External audio router]).
+to the hybrid system. ( [Different types of sources]( {{< ref "#different-types-of-sources" >}} ),
+ [External audio router]( {{< ref "#external-audio-router" >}} )).
### Priority rules
@@ -310,37 +310,37 @@ the application with a meaningful error.
When an application attempts to play audio and the audio manager is unable to
allocate a necessary audio resource (for example because a higher-priority
stream is already playing), the audio manager must inform the application using
-an appropriate error message. ([][Emergency call priority])
+an appropriate error message. ( [Emergency call priority]( {{< ref "#emergency-call-priority" >}} ))
### Multiple sound outputs
The audio manager should be able to route sounds to several sound outputs.
-([][Different types of sources]).
+( [Different types of sources]( {{< ref "#different-types-of-sources" >}} )).
### Remember preempted source
It should be possible for an audio source that was preempted
to be remembered in order to resume it after interruption.
This is not a necessity for all types of streams. Some OEM-specific code could
-select those streams based on their roles. ([][Traffic bulletin], [][Resume music])
+select those streams based on their roles. ( [Traffic bulletin]( {{< ref "#traffic-bulletin" >}} ), [Resume music]( {{< ref "#resume-music" >}} ))
### Audio recording
App-bundles must be able to record audio if given appropriate permission.
-([][Audio recording])
+( [Audio recording]( {{< ref "#audio-recording" >}} ))
### Latency
The telephony latency must be as low as possible. The user must be able to
hold a conversation on the phone or in a VoIP application without noticing any
-form of latency. ([][VoIP])
+form of latency. ( [VoIP]( {{< ref "#voip" >}} ))
### Security
The audio manager should not trust applications for managing audio. If some faulty
or malicious application tries to play or record an audio stream for which
permission wasn't granted, the proposed audio management design should not
-allow it. ([][Application crash], [][Control malicious application])
+allow it. ( [Application crash]( {{< ref "#application-crash" >}} ), [Control malicious application]( {{< ref "#control-malicious-application" >}} ))
### Muting output streams
@@ -348,19 +348,19 @@ During the time an audio source is preempted, the audio framework must notify
the application that is providing it, so that the application can make an
attempt to reduce its resource usage. For example, a DAB radio application
might stop decoding the received DAB data.
-([][Mute], [][Traffic bulletin])
+( [Mute]( {{< ref "#mute" >}} ), [Traffic bulletin]( {{< ref "#traffic-bulletin" >}} ))
### Muting input streams
The audio framework should be able to mute capture streams. During that time,
the audio framework must notify the application that are using it, so that the
application can update user interface and reduce its resource usage.
-([][Microphone mute])
+( [Microphone mute]( {{< ref "#microphone-mute" >}} ))
### Control source activity
Audio management should be able to set each audio source to the playing,
-stopped or paused state based on priority. ([][Resume music])
+stopped or paused state based on priority. ( [Resume music]( {{< ref "#resume-music" >}} ))
### Per stream priority
@@ -369,7 +369,7 @@ automotive domain.
An application might want to send different types of alert. For instance, a
new message notification may have higher priority than 'some contact published
a new photo'.
-([][Multiple roles])
+( [Multiple roles]( {{< ref "#multiple-roles" >}} ))
### GStreamer support
diff --git a/content/designs/canterbury-legacy-application-framework.md b/content/designs/canterbury-legacy-application-framework.md
index 90e7f359f775216f186ba62695c18758fef1d617..cd44c7f2f9946c87f2288b71a6c3ed155a426ac4 100644
--- a/content/designs/canterbury-legacy-application-framework.md
+++ b/content/designs/canterbury-legacy-application-framework.md
@@ -10,7 +10,7 @@ outputs = [ "html", "pdf-in",]
Apertis currently ships with a custom application framework based on the
Canterbury app manager which is in the process of being phased out in favor of
-upstream components like Flatpak, see the [](application-framework.md)
+upstream components like Flatpak, see the[application framework]( {{< ref "application-framework.md" >}} )
document for more details.
Flatpak and Canterbury cover the core tasks of an application framework:
@@ -147,7 +147,7 @@ profiles for each applications can carefully reviewing them.
Flatpak instead lets application authors specify in the application manifest a
set of special high-level permissions. The Flatpak approach has been analysed
-in more detail in the original [](permissions.md) document which already
+in more detail in the original[permissions]( {{< ref "permissions.md" >}} ) document which already
described the use-cases for the permissions mechanism in the context of the
Apertis application framework.
diff --git a/content/designs/closing-ci-loop.md b/content/designs/closing-ci-loop.md
index 7eec859b61ef39babda6d5059a80dbff27fefdb0..ea7c615072c73122b87f9f62482f01d62d9afd49 100644
--- a/content/designs/closing-ci-loop.md
+++ b/content/designs/closing-ci-loop.md
@@ -211,8 +211,7 @@ One of the most important phases in closing the loop is reporting tests issues i
Phabricator.
Tests issues will be reported automatically in Phabricator as tasks per test cases
-instead of tasks per issues. This has an important consequence explained in the
-[](#considerations) section.
+instead of tasks per issues. This has an important consequence explained in the[considerations]( {{< ref "#considerations" >}} ) section.
This section gives an overview for the behaviour of this phase.
@@ -349,7 +348,7 @@ execute the `task manager` and later (if available) to the `notifier`.
This is a diagram explaining the different infrastructure processes involved in
the proposed design to close the CI loop.
-
+
# Security Improvement
@@ -395,10 +394,10 @@ infrastructure services, so other teams and projects can also make use of it.
- The test definitions for public LAVA jobs are publicly visible. The Jenkins
webhook URL will also be visible in these tests definitions, which can be a
security concern. A solution for this issue is proposed in
- [](#security-improvement).
+ [security improvement]( {{< ref "#security-improvement" >}} ).
- Closing and verifying tasks will still require manual intervention due to
- the points explained in the [](#considerations) section.
+ the points explained in the[considerations]( {{< ref "#considerations" >}} ) section.
# New CI Infrastructure and Workflow
@@ -473,7 +472,7 @@ Phabricator tasks and send notifications.
to be processed by other phases in the tests processor system, and sent to a
new phase to manage Phabricator tasks.
- The new Phabricator phase uses the tests data to file new tasks following the
- logic explained in the [](#tasks-management) section.
+ logic explained in the[tasks management]( {{< ref "#tasks-management" >}} ) section.
- The same phase or a new one could notify results to mattermost or via email.
### Reporting and Visualization
@@ -522,7 +521,7 @@ steps:
The following diagram shows the visual for the above workflow:
-
+
## New Infrastructure Migration Steps
diff --git a/content/designs/clutter.md b/content/designs/clutter.md
index d77471d2a19c2c076f737514c0f16ae27942f4a6..a77be151be6bb089183982e99e349b0c610aa573 100644
--- a/content/designs/clutter.md
+++ b/content/designs/clutter.md
@@ -40,7 +40,7 @@ overcoming them.
For the purposes of this document, the MT stack on X.Org is layered as
follows:
-
+
#### Compositor
@@ -280,7 +280,7 @@ for applications and the compositor will decline ownership immediately.
This diagram illustrates how the different components interact when
handling touch events:
-
+
If there is a window that gets placed on top of the others
(specifically, the “busy†indicator animation) and it shouldn't get any
diff --git a/content/designs/connectivity.md b/content/designs/connectivity.md
index b0841ba54b461ebe39fa5b10732c6413caf5a7e7..64fe26aa1999f9b5087f2a1c240344ceb0367ead 100644
--- a/content/designs/connectivity.md
+++ b/content/designs/connectivity.md
@@ -18,27 +18,27 @@ speed causing WiFi networks to come and go quickly, low cell phone
signal strength, and so on. On the other hand, potentially good
connectivity while parked, since the user might have high quality WiFi
at the office and at home. Network Management will be discussed in
-[][Network management].
+ [Network management]( {{< ref "#network-management" >}} ).
Online and cellular-based real-time communications, including chatting,
voice calls, VoIP and video calls are covered in
-[][Real-time communications].
+ [Real-time communications]( {{< ref "#real-time-communications" >}} ).
It is very common these days to have people carrying one or more smart
devices with them. People want those smart devices to connect to their
in-vehicle infotainment system for playing audio, importing contacts and
also use or share Internet connections. This is discussed in
-[][Tethering from mobile devices].
+ [Tethering from mobile devices]( {{< ref "#tethering-from-mobile-devices" >}} ).
The main medium used for inter-device communication, Bluetooth, and its
-various profiles are discussed in [][Bluetooth support]. A brief
+various profiles are discussed in [Bluetooth support]( {{< ref "#bluetooth-support" >}} ). A brief
discussion of using GPS to enhance network management and about the
-GeoClue framework are the subject of [][Global Positioning System (GPS)].
+GeoClue framework are the subject of [Global Positioning System (GPS)]( {{< ref "#global-positioning-system-gps" >}} ).
Contacts management is covered by a separate document. Integration with
other devices by means other than Bluetooth and USB mass-storage, such
as reading songs off of an iPod is the topic discussed in
-[][Media downloading].
+ [Media downloading]( {{< ref "#media-downloading" >}} ).
## Network management
@@ -65,7 +65,7 @@ to provide that integration, allowing ConnMan to use Bluetooth devices
to go online. Illustration has a schematic view of the interactions
among these frameworks.
-
+
### Switching to a different connection
@@ -398,7 +398,7 @@ addition to the driver, pairing of the device by a user-space program is
required. That pairing can be performed either by using the standalone
tool provided at the project's web page or through the tools distributed
by the **libimobiledevice** project, discussed in
-[][Media downloading].
+ [Media downloading]( {{< ref "#media-downloading" >}} ).
Collabora believes the three main components discussed here, BlueZ,
oFono and ConnMan are capable of supporting tethering to most mobile
@@ -514,8 +514,8 @@ Port Profile allows emulation of serial ports over a Bluetooth link.
### PAN and DUN
-As discussed in sections [][Network management] and
-[][Tethering from mobile devices],
+As discussed in sections [Network management]( {{< ref "#network-management" >}} ) and
+ [Tethering from mobile devices]( {{< ref "#tethering-from-mobile-devices" >}} ),
BlueZ provides support for the Personal Area Networking
**(PAN)** profile both in the NAP role (BlueZ acting as connection
provider) or PANU role (BlueZ using a internet connection over
@@ -626,7 +626,7 @@ cancellation solution just by rewriting the sub-module.
The diagram in Illustration shows how the various pieces of such a
set-up are related.
-
+
### HSP
diff --git a/content/designs/contacts.md b/content/designs/contacts.md
index 2807dac29ee55383967d1e16454fca63ab285521..3897c22096cfcf1068e4b671f7f6386e8c0035bb 100644
--- a/content/designs/contacts.md
+++ b/content/designs/contacts.md
@@ -48,14 +48,14 @@ library, Collabora is ready and able to adjust this design.
There are many potential sources for contacts, as people's contact
details are frequently split over many services. The proposed system
aggregates contacts from multiple sources in a way that is seamless to
-the user. See the [][Components] section on [][Folks]
+the user. See the [Components]( {{< ref "#components" >}} ) section on [Folks]( {{< ref "#folks" >}} )
for more details of the components involved.
### Local Sources
New contacts may be created locally by importing contacts from a
-[][Bluetooth-paired phone] or a contact
-editor dialog (see [][User interfaces]).
+ [Bluetooth-paired phone]( {{< ref "#bluetooth-paired-phone" >}} ) or a contact
+editor dialog (see [User interfaces]( {{< ref "#user-interfaces" >}} )).
These local contacts may contain a wide variety of detail types,
including (but not limited to):
@@ -139,8 +139,8 @@ The growing number of web services with social networking is yet another
source of contacts for many users. Some services may provide useful
contact information, such as postal addresses or phone numbers. In these
cases, it may be worthwhile to include web service contacts (since
-implementation for some services already exist within [][Folks]
-and [][libsocialweb].
+implementation for some services already exist within [Folks]( {{< ref "#folks" >}} )
+and [libsocialweb]( {{< ref "#libsocialweb" >}} ).
In the case of multi-seat configurations, it may also be worthwhile to
support additional web services for entertainment purposes. Potential
@@ -163,11 +163,11 @@ these contacts, even when offline.
Contacts may be retrieved from a SIM card within a vehicle's built-in
mobile phone stack. These contacts will be accessible from the Apertis
contacts system. However, any changes to these contacts will not be
-written back to the SIM card. See [][Read-only operation for external sources].
+written back to the SIM card. See [Read-only operation for external sources]( {{< ref "#read-only-operation-for-external-sources" >}} ).
### Read-only Operation for External Sources
-Modifications of contacts will be limited to [][Local sources].
+Modifications of contacts will be limited to [Local sources]( {{< ref "#local-sources" >}} ).
Depending upon the user interfaces created, users
may be able to set details upon local contacts which may appear to
affect external contacts such as web service contacts or
@@ -179,9 +179,9 @@ actually be written to the corresponding contact on the external source.
### Contact Management
Our proposed system will support adding, editing, and removing contacts.
-New contacts will be added to [][Local sources]. Though the [][Components]
+New contacts will be added to [Local sources]( {{< ref "#local-sources" >}} ). Though the [Components]( {{< ref "#components" >}} )
which will enable contact management already
-support these features, [][User interfaces]
+support these features, [User interfaces]( {{< ref "#user-interfaces" >}} )
needs to be implemented to present these functions
to the user. Similarly, contacts will need to be presented as necessary
by end-user applications.
@@ -356,7 +356,7 @@ the C/C++ and Vala bindings.
#### Required work
-As described in [][Contact aggregation and linking], our system will support automatic linking of
+As described in [Contact aggregation and linking]( {{< ref "#contact-aggregation-and-linking" >}} ), our system will support automatic linking of
contacts as well as anti-linking (for mismatched automatic links). Folks
currently supports recommending links but does not yet act upon these
recommendations automatically, so this would need to be implemented.
@@ -380,7 +380,7 @@ Additionally, the ability to perform “deepâ€
searches will require support for [search-only backends].
The search functionality will also need to support sorting and
-pagination as described in [][Sorting and pagination]
+pagination as described in [Sorting and pagination]( {{< ref "#sorting-and-pagination" >}} )
before it can be merged upstream.
Folks external contact sources will need the ability to be designated as
@@ -398,7 +398,7 @@ hardware.
Abstract contact address book creation and deletion within Folks will
require new work.
-In case [][Opportunistic caching] is required for the
+In case [Opportunistic caching]( {{< ref "#opportunistic-caching" >}} ) is required for the
contacts system, this will need to be added as a new feature to Folks
and its Telepathy and libsocialweb backends.
@@ -470,7 +470,7 @@ In the case that we support web service contacts, libsocialweb will be
the component that provides these contacts through its Folks backend.
Note that exactly which web services can be used depends upon both
implementation in libsocialweb and license agreements with those
-services. See [][Web services] for more details.
+services. See [Web services]( {{< ref "#web-services" >}} ) for more details.
### SyncEvolution
@@ -487,7 +487,7 @@ is widely supported by most Bluetooth stacks, including [BlueZ].
### Zeitgeist
[Zeitgeist] is open source event-tracking software that will serve
-as the [][Event logging] service for Apertis. It is a
+as the [Event logging]( {{< ref "#event-logging" >}} ) service for Apertis. It is a
flexible event store and uses external services to store their events in
a central location. So, by its nature, it supports third-party
applications without prior knowledge of them.
diff --git a/content/designs/debug-and-logging.md b/content/designs/debug-and-logging.md
index d53e08d5a79d9b28ed86cb3b566a299a0cbfafde..d9792f70fb37b22fa9300b808ee9c5a9314bd9fa 100644
--- a/content/designs/debug-and-logging.md
+++ b/content/designs/debug-and-logging.md
@@ -195,7 +195,7 @@ application developers.
The tool must allow interactive walking through the stack, printing
expressions, and other common C debugging functions.
-See [][Debug deterministic application on SDK].
+See [Debug deterministic application on SDK]( {{< ref "#debug-deterministic-application-on-sdk" >}} ).
### Code debugger can be used remotely
@@ -203,7 +203,7 @@ The code debugger must be usable remotely in real time, most likely with
a server component running on the target device, and a client component
on the developer’s machine.
-See [][Debug application on target].
+See [Debug application on target]( {{< ref "#debug-application-on-target" >}} ).
### Code record and replay tool installable on development and target machines
@@ -220,9 +220,9 @@ When replaying logs, the developer must be able to use a debugger to
investigate problems.
See:
- - [][Debug non-deterministic application on SDK]
- - [][Debug application in the context of the whole system]
- - [][Record and replay logs for input to an application]
+ - [Debug non-deterministic application on SDK]( {{< ref "#debug-non-deterministic-application-on-sdk" >}} )
+ - [Debug application in the context of the whole system]( {{< ref "#debug-application-in-the-context-of-the-whole-system" >}} )
+ - [Record and replay logs for input to an application]( {{< ref "#record-and-replay-logs-for-input-to-an-application" >}} )
### Application logs available in Eclipse when run on the SDK
@@ -231,7 +231,7 @@ application uses must send their output to the Eclipse console (i.e.
stdout or stderr) rather than (or as well as) the SDK system’s journal.
This allows the developer to easily read those messages.
-See [][Debug deterministic application on SDK].
+See [Debug deterministic application on SDK]( {{< ref "#debug-deterministic-application-on-sdk" >}} ).
### Whole system logs are aggregated and timestamped
@@ -251,8 +251,8 @@ must be available to the developer to allow them to filter logs for
relevant messages.
See:
- - [][Debug deterministic application on SDK]
- - [][Debug application on target]
+ - [Debug deterministic application on SDK]( {{< ref "#debug-deterministic-application-on-sdk" >}} )
+ - [Debug application on target]( {{< ref "#debug-application-on-target" >}} )
### Whole system logs are limited by priority and rotated
@@ -267,7 +267,7 @@ vehicle is running, for example to allow them to be uploaded to an
online diagnosis service in case of a fault. They must not, however, be
written to disk.
-See [][Logging storage space is limited in post-production].
+See [Logging storage space is limited in post-production]( {{< ref "#logging-storage-space-is-limited-in-post-production" >}} ).
### Extract whole system logs from target device
@@ -276,7 +276,7 @@ accessible by the developer, who must be able to copy it to their
development machine for analysis. The log does not necessarily have to
be extractable in real time, though that would be helpful.
-See [][Extract logs from a device under test].
+See [Extract logs from a device under test]( {{< ref "#extract-logs-from-a-device-under-test" >}} ).
### Extract whole system logs from target device in post-production
@@ -285,7 +285,7 @@ extractable by a trusted dealer so that It can be sent to an Apertis
developer for analysis. Extracting the log may require physical access
to the vehicle.
-See [][Trusted dealer can extract logs from a device post-production].
+See [Trusted dealer can extract logs from a device post-production]( {{< ref "#trusted-dealer-can-extract-logs-from-a-device-post-production" >}} ).
### Protect access to whole system logs on production devices
@@ -293,7 +293,7 @@ The aggregated system log on a production device must only be
extractable by a trusted dealer or other authorised representative of
the vehicle manufacturer.
-See [][Third-party cannot extract logs from a device post-production].
+See [Third-party cannot extract logs from a device post-production]( {{< ref "#third-party-cannot-extract-logs-from-a-device-post-production" >}} ).
### Code record and replay tool can handle multiple processes
@@ -301,7 +301,7 @@ The code record and replay tool must be able to record and replay a
single log for multiple processes, such as an application and its
agents. They must all see the same timing information.
-See [][Record and replay logs for input to an application].
+See [Record and replay logs for input to an application]( {{< ref "#record-and-replay-logs-for-input-to-an-application" >}} ).
### Record and replay SDK sensor data
@@ -309,7 +309,7 @@ It must be possible to record all D-Bus traffic to and from the SDK
sensors API for a given time period (a ‘trip’), and later replay that
log to the whole system instead of using current sensor data.
-See [][Record and replay logs for sensors to the whole system].
+See [Record and replay logs for sensors to the whole system]( {{< ref "#record-and-replay-logs-for-sensors-to-the-whole-system" >}} ).
### Profiling tools installable on development and target machines
@@ -317,7 +317,7 @@ A variety of profiling tools must be available in Apertis, and
installable on development and target machines so that they can be used
by Apertis and application developers.
-See [][Performance profiling].
+See [Performance profiling]( {{< ref "#performance-profiling" >}} ).
### Rate limiting of whole system logs
@@ -326,7 +326,7 @@ must be applied to log message submissions from each application. If an
application submits log messages at too high a rate, the extras must be
dropped.
-See [][Denial of service attack on logging].
+See [Denial of service attack on logging]( {{< ref "#denial-of-service-attack-on-logging" >}} ).
### Applications can write their own log files
@@ -335,7 +335,7 @@ SDK logging infrastructure with their own system which writes to a log
file in their application’s storage space. This must be permitted,
although the SDK does not have to provide convenience API for it.
-See [][Private application log file].
+See [Private application log file]( {{< ref "#private-application-log-file" >}} ).
### Disk usage for each application is limited
@@ -346,7 +346,7 @@ working by consuming all free disk space. If the application consumes
too much disk space, the system may delete its files or prevent it from
working.
-See [][Private application log file].
+See [Private application log file]( {{< ref "#private-application-log-file" >}} ).
## Existing debug and logging systems
@@ -499,7 +499,7 @@ only on development images) should be written which logs all traffic for
a specified D-Bus bus to the systemd journal.
Note that this does not allow for log replay. For specific cases, this
-will be handled using [][Trip logging of SDK sensor data].
+will be handled using [Trip logging of SDK sensor data]( {{< ref "#trip-logging-of-sdk-sensor-data" >}} ).
### Trip logging of SDK sensor data
@@ -671,54 +671,54 @@ as later stages in the implementation.
### Requirements
- - [][Code debugger installable on development and target machines]:
+ - [Code debugger installable on development and target machines]( {{< ref "#code-debugger-installable-on-development-and-target-machines" >}} ):
GDB is the debugger.
- - [][Code debugger can be used remotely]:
+ - [Code debugger can be used remotely]( {{< ref "#code-debugger-can-be-used-remotely" >}} ):
GDB can be used with gdbserver.
- - [][Code record and replay tool installable on development and target machines]:
+ - [Code record and replay tool installable on development and target machines]( {{< ref "#code-record-and-replay-tool-installable-on-development-and-target-machines" >}} ):
rr is the record and replay tool.
- - [][Application logs available in Eclipse when run on the SDK]:
+ - [Application logs available in Eclipse when run on the SDK]( {{< ref "#application-logs-available-in-eclipse-when-run-on-the-sdk" >}} ):
Outputting log entries to stdout or stderr if running on a console.
- - [][Whole system logs are aggregated and timestamped]:
+ - [Whole system logs are aggregated and timestamped]( {{< ref "#whole-system-logs-are-aggregated-and-timestamped" >}} ):
All system logs are forwarded to the systemd journal. D-Bus messages are logged
to the journal via a new D-Bus logging service.
- - [][Whole system logs are tagged by process and priority]:
+ - [Whole system logs are tagged by process and priority]( {{< ref "#whole-system-logs-are-tagged-by-process-and-priority" >}} ):
Done by the systemd journal by default.
- - [][Whole system logs are limited by priority and rotated]:
+ - [Whole system logs are limited by priority and rotated]( {{< ref "#whole-system-logs-are-limited-by-priority-and-rotated" >}} ):
Done with suitable configuration of the systemd journal.
- - [][Extract whole system logs from target device]:
+ - [Extract whole system logs from target device]( {{< ref "#extract-whole-system-logs-from-target-device" >}} ):
DLT is used to extract logs and transfer them to a developer machine in real time.
- - [][Extract whole system logs from target device in post-production]
+ - [Extract whole system logs from target device in post-production]( {{< ref "#extract-whole-system-logs-from-target-device-in-post-production" >}} )
New journal export service exposing an
authenticated interface for exporting systemd journal logs.
- - [][Protect access to whole system logs on production devices]:
+ - [Protect access to whole system logs on production devices]( {{< ref "#protect-access-to-whole-system-logs-on-production-devices" >}} ):
Journal export service requires authentication.
- - [][Code record and replay tool can handle multiple processes]:
+ - [Code record and replay tool can handle multiple processes]( {{< ref "#code-record-and-replay-tool-can-handle-multiple-processes" >}} ):
rr supports logging and replaying to multiple processes.
- - [][Record and replay SDK sensor data]:
+ - [Record and replay SDK sensor data]( {{< ref "#record-and-replay-sdk-sensor-data" >}} ):
D-Bus record and replay tool will be used for this.
- - [][Profiling tools installable on development and target machines]:
+ - [Profiling tools installable on development and target machines]( {{< ref "#profiling-tools-installable-on-development-and-target-machines" >}} ):
Various profiling tools will be packaged.
- - [][Rate limiting of whole system logs]:
+ - [Rate limiting of whole system logs]( {{< ref "#rate-limiting-of-whole-system-logs" >}} ):
Done with suitable configuration of the systemd journal.
- - [][Applications can write their own log files]:
+ - [Applications can write their own log files]( {{< ref "#applications-can-write-their-own-log-files" >}} ):
Allowed for any application which is allowed to write files.
- - [][Disk usage for each application is limited]:
+ - [Disk usage for each application is limited]( {{< ref "#disk-usage-for-each-application-is-limited" >}} ):
Each application writes to its own file system as in the Robustness design.
## Open questions
diff --git a/content/designs/geolocation-and-navigation.md b/content/designs/geolocation-and-navigation.md
index acc7e73bda9698fc452725db89f89ce52275c4d0..caf5b35098f2dbf23ad617189a81d6e37c3f7efd 100644
--- a/content/designs/geolocation-and-navigation.md
+++ b/content/designs/geolocation-and-navigation.md
@@ -44,7 +44,7 @@ of geo-related features used by other applications. This
means that the navigation routing API suggested by this design is
limited to allowing applications to interact with an external navigation
routing system, rather than implement or embed one themselves.
-[][Appendix: Recommendations for third-party navigation applications]
+ [Appendix: Recommendations for third-party navigation applications]( {{< ref "#appendix-recommendations-for-third-party-navigation-applications" >}} )
when implementing a navigation application are given.
## Terminology and concepts
@@ -184,7 +184,7 @@ the bottom of each use case.
In all of these use cases, unless otherwise specified, the functionality
must work regardless of whether the vehicle has an internet connection.
i.e. They must work offline. For most APIs, this is the responsibility
-of the automotive backend; [][SDK backend] can
+of the automotive backend; [SDK backend]( {{< ref "#sdk-backend" >}} ) can
assume an internet connection is always available.
### Relocating the vehicle
@@ -543,7 +543,7 @@ other two angles of movement, the rate of change of angle of movement in
all three dimensions, and uncertainty bounds and standard deviation for
all measurements if known.
-See [][Relocating the vehicle].
+See [Relocating the vehicle]( {{< ref "#relocating-the-vehicle" >}} ).
### Geolocation service supports signals
@@ -554,14 +554,14 @@ between updates, either of which may be zero. The bundle should also be
able to specify a *minimum* time between updates, in order to prevent
being overwhelmed by updates.
-See [][Navigating to a location].
+See [Navigating to a location]( {{< ref "#navigating-to-a-location" >}} ).
### Geolocation implements caching
If an up-to-date location is not known, the geolocation API may return a
cached location with an appropriate time of measurement.
-See [][Relocating the vehicle], [][Tasks nearby].
+See [Relocating the vehicle]( {{< ref "#relocating-the-vehicle" >}} ), [Tasks nearby]( {{< ref "#tasks-nearby" >}} ).
### Geolocation supports backends
@@ -572,8 +572,8 @@ a particular distribution of Apertis being a runtime decision.
The default navigation application (requirement 5.6) must be able to
feed geolocation information into the service as an additional backend.
-See [][Automotive backend],
-[][Third-party navigation-driven refinement of geolocation]
+See [Automotive backend]( {{< ref "#automotive-backend" >}} ),
+ [Third-party navigation-driven refinement of geolocation]( {{< ref "#third-party-navigation-driven-refinement-of-geolocation" >}} )
### Navigation routing API
@@ -598,12 +598,12 @@ It must provide a way to request navigation routing suitable for walking or
cycling, so that the driver knows how to reach a point of interest after they
leave the vehicle.
-See [][Navigating to a location],
-[][Changing destination during navigation],
-[][Navigating via waypoints],
-[][Navigating a tour],
-[][Navigating to an entire city],
-[][No navigation application].
+See [Navigating to a location]( {{< ref "#navigating-to-a-location" >}} ),
+ [Changing destination during navigation]( {{< ref "#changing-destination-during-navigation" >}} ),
+ [Navigating via waypoints]( {{< ref "#navigating-via-waypoints" >}} ),
+ [Navigating a tour]( {{< ref "#navigating-a-tour" >}} ),
+ [Navigating to an entire city]( {{< ref "#navigating-to-an-entire-city" >}} ),
+ [No navigation application]( {{< ref "#no-navigation-application" >}} ).
### Navigation routing supports different navigation applications
@@ -611,8 +611,8 @@ The mechanism for launching the navigation application (requirement 5.5)
must allow a third-party navigation application to be set as the
default, handling all requests.
-See [][Installing a navigation application],
-[][Third-party navigation-driven refinement of geolocation].
+See [Installing a navigation application]( {{< ref "#installing-a-navigation-application" >}} ),
+ [Third-party navigation-driven refinement of geolocation]( {{< ref "#third-party-navigation-driven-refinement-of-geolocation" >}} ).
### Navigation route list API
@@ -627,8 +627,8 @@ is calculated to avoid bad traffic.
If no navigation application is installed, the route list API must
continue to be usable, and must return an error code to callers.
-See [][Navigation route guidance information],
-[][No navigation application].
+See [Navigation route guidance information]( {{< ref "#navigation-route-guidance-information" >}} ),
+ [No navigation application]( {{< ref "#no-navigation-application" >}} ).
### Navigation route guidance API
@@ -648,7 +648,7 @@ which is part of the system UI. It must support being called by the
navigation application when the next turn-by-turn instruction needs to
be presented, or the estimated journey end time changes.
-See [][Navigation route guidance information].
+See [Navigation route guidance information]( {{< ref "#navigation-route-guidance-information" >}} ).
### Type-ahead search and address completion supports backends
@@ -656,8 +656,8 @@ The address completion implementation must support multiple backend
implementations, with the selection of backend or backends to be used in
a particular distribution of Apertis being a runtime decision.
-See [][Automotive backend],
-[][Type-ahead search and completion for addresses].
+See [Automotive backend]( {{< ref "#automotive-backend" >}} ),
+ [Type-ahead search and completion for addresses]( {{< ref "#type-ahead-search-and-completion-for-addresses" >}} ).
### Geocoding supports backends
@@ -665,7 +665,7 @@ The geocoding implementation must support multiple backend
implementations, with the selection of backend or backends to be used in
a particular distribution of Apertis being a runtime decision.
-See [][Automotive backend].
+See [Automotive backend]( {{< ref "#automotive-backend" >}} ).
### SDK has default implementations for all backends
@@ -677,7 +677,7 @@ The SDK implementation must support all functionality of the geo-APIs in
order to allow app developers to test all functionality used by their
applications.
-See [][SDK backend].
+See [SDK backend]( {{< ref "#sdk-backend" >}} ).
### SDK APIs do not vary with backend
@@ -690,8 +690,8 @@ vendor-specific proprietary APIs to communicate with the automotive
domain, that must be possible; but other applications must not use these
APIs.
-See [][Automotive backend],
-[][Custom automotive backend functionality].
+See [Automotive backend]( {{< ref "#automotive-backend" >}} ),
+ [Custom automotive backend functionality]( {{< ref "#custom-automotive-backend-functionality" >}} ).
### Third-party navigation applications can be used as backends
@@ -699,7 +699,7 @@ A third-party or OEM-provided navigation application must, if it
implements the correct interfaces, be able to act as a backend for some
or all geo-functionality.
-See [][Third-party navigation application backend].
+See [Third-party navigation application backend]( {{< ref "#third-party-navigation-application-backend" >}} ).
### Backends operate asynchronously
@@ -710,13 +710,13 @@ and tolerant of latency.
See the Inter-Domain Communications design.
-See [][Web-based backend].
+See [Web-based backend]( {{< ref "#web-based-backend" >}} ).
### 2D map rendering API
Map display has the following requirements:
- - Rendering the map (see [][Relocating the vehicle]).
+ - Rendering the map (see [Relocating the vehicle]( {{< ref "#relocating-the-vehicle" >}} )).
- Rendering points of interest, including start and destination points
for navigation.
@@ -738,8 +738,8 @@ Map display has the following requirements:
- Optionally rendering the vehicle’s current position as a map layer
(see [Relocating the vehicle][Relocating the vehicle]).
-See [][Viewing an address on the map],
-[][Adding custom widgets on the map].
+See [Viewing an address on the map]( {{< ref "#viewing-an-address-on-the-map" >}} ),
+ [Adding custom widgets on the map]( {{< ref "#adding-custom-widgets-on-the-map" >}} ).
### 2.5D or 3D map rendering API
@@ -747,7 +747,7 @@ For applications which wish to present a perspective view of a map, a
2.5D or 3D map widget should be provided with all the same features as
the 2D map rendering API.
-See [][2.5D or 3D map widget].
+See [2.5D or 3D map widget]( {{< ref "#25d-or-3d-map-widget" >}} ).
### Reverse geocoding API
@@ -758,7 +758,7 @@ around a given reference coordinate pair must be supported.
Reverse geocoding may work when the vehicle has no internet connection,
but only if that is easy to implement.
-See [][Viewing an address on the map].
+See [Viewing an address on the map]( {{< ref "#viewing-an-address-on-the-map" >}} ).
### Forward geocoding API
@@ -769,7 +769,7 @@ results should be supported.
Forward geocoding may work when the vehicle has no internet connection,
but only if that is easy to implement.
-See [][Finding the address of a location on the map].
+See [Finding the address of a location on the map]( {{< ref "#finding-the-address-of-a-location-on-the-map" >}} ).
### Type-ahead search and address completion API
@@ -786,7 +786,7 @@ such as typing suggestions and keyboard history. If the functionality
cannot be implemented or the service for it is not available, the system
should provide a normal text entry box to the user.
-See [][Type-ahead search and completion for addresses].
+See [Type-ahead search and completion for addresses]( {{< ref "#type-ahead-search-and-completion-for-addresses" >}} ).
### Geofencing API
@@ -796,7 +796,7 @@ entering, exiting, or dwelling in a region. The vehicle is dwelling in a
region if it has been in there for a specified amount of time without
exiting.
-See [][Tasks nearby], [][Turning on house lights].
+See [Tasks nearby]( {{< ref "#tasks-nearby" >}} ), [Turning on house lights]( {{< ref "#turning-on-house-lights" >}} ).
### Geofencing service can wake up applications
@@ -804,7 +804,7 @@ It must be possible for geofencing signals to be delivered even if the
application bundle which registered to receive them is not currently
running.
-See [][Tasks nearby], [][Turning on house lights].
+See [Tasks nearby]( {{< ref "#tasks-nearby" >}} ), [Turning on house lights]( {{< ref "#turning-on-house-lights" >}} ).
### Geofencing API signals on national borders
@@ -813,7 +813,7 @@ borders of the current country, which applications may subscribe to
signals about, and be woken up for as normal, if the vehicle crosses the
country’s border.
-See [][Traffic rule application].
+See [Traffic rule application]( {{< ref "#traffic-rule-application" >}} ).
### Geocoding API must be locale-aware
@@ -822,7 +822,7 @@ as addresses, in a localised form. The localisation must be configurable
so that, for example, the user’s home locale could be used, or the
locale of the country the vehicle is currently in.
-See [][Traffic rule application].
+See [Traffic rule application]( {{< ref "#traffic-rule-application" >}} ).
### Geolocation provides error bounds
@@ -830,16 +830,16 @@ The geolocation API must provide an error bound for each location
measurement it returns, so calling code knows how accurate that data is
likely to be.
-See [][Temporary loss of GPS signal].
+See [Temporary loss of GPS signal]( {{< ref "#temporary-loss-of-gps-signal" >}} ).
### Geolocation implements dead-reckoning
The geolocation API must implement dead reckoning based on the vehicle’s
previous velocity, to allow a location to be returned even if GPS signal
is lost. This must update the error bounds appropriately
-([][Geolocation provides error bounds]).
+( [Geolocation provides error bounds]( {{< ref "#geolocation-provides-error-bounds" >}} )).
-See [][Temporary loss of GPS signal].
+See [Temporary loss of GPS signal]( {{< ref "#temporary-loss-of-gps-signal" >}} ).
### Geolocation uses navigation and sensor data if available
@@ -848,7 +848,7 @@ sensor data to improve the accuracy of the location it reports, for
example by snapping the GPS location to the nearest road on the map
using information provided by the navigation application.
-See [][Navigation- and sensor-driven refinement of geolocation].
+See [Navigation- and sensor-driven refinement of geolocation]( {{< ref "#navigation--and-sensor-driven-refinement-of-geolocation" >}} ).
### General points of interest streams are queryable
@@ -869,7 +869,7 @@ Further requirements and designs specific to how applications expose
such general points of interest streams are covered in the Points of
Interest design.
-See [][Application-driven refinement of geocoding].
+See [Application-driven refinement of geocoding]( {{< ref "#application-driven-refinement-of-geocoding" >}} ).
### Location information requires permissions to access
@@ -888,7 +888,7 @@ Application bundles asking for fine-grained location data must be
subjected to closer review when submitted to the Apertis application
store.
-See [][Malware application bundle].
+See [Malware application bundle]( {{< ref "#malware-application-bundle" >}} ).
**Open question**: What review checks should be performed on application
bundles which request permissions for location data?
@@ -901,7 +901,7 @@ applications by limiting the number of points of interest they can feed
to the geolocation and other services, both in the rate at which they
are transferred, and the number present in the system at any time.
-See [][Excessive results from application-driven refinement of geocoding].
+See [Excessive results from application-driven refinement of geocoding]( {{< ref "#excessive-results-from-application-driven-refinement-of-geocoding" >}} ).
### Application-provided data requires permissions to create
@@ -911,7 +911,7 @@ or points of interest, without needing to uninstall that application
(i.e. so they can continue to use other functionality from the
application).
-See [][User control over applications].
+See [User control over applications]( {{< ref "#user-control-over-applications" >}} ).
## Existing geo systems
@@ -1220,7 +1220,7 @@ the device’s location.
## Approach
-Based on the [][Existing geo systems]) and [][Requirements], we
+Based on the [Existing geo systems]( {{< ref "#existing-geo-systems" >}} )) and [Requirements]( {{< ref "#requirements" >}} ), we
recommend the following approach for integrating geo-features into
Apertis. The overall summary is to use existing freedesktop.org and
GNOME components for all geo-features, adding features to them where
@@ -1266,9 +1266,9 @@ Third-party applications (such as navigation applications) may provide
backends for geo-services as dynamically loaded libraries which are
installed as part of their application bundle. As this allows arbitrary
code to be run in the context of the geo-services (which form security
-boundaries for applications, see [][Systemic security]),
+boundaries for applications, see [Systemic security]( {{< ref "#systemic-security" >}} )),
the code for these third-party backends must be audited and tested
-([][Testing backends]) carefully as part of the app store validation process.
+( [Testing backends]( {{< ref "#testing-backends" >}} )) carefully as part of the app store validation process.
Due to the potential for inter-domain communications, or for backends
which access web services to provide functionality, the backend and SDK
@@ -1284,8 +1284,8 @@ future.
Throughout this design, the phrase *navigation application* should be
taken to mean the navigation application bundle, including its UI, a
-potentially separate [][Route guidance ui] and any agents or
-backends for [][Backends]. While the navigation application
+potentially separate [Route guidance ui]( {{< ref "#route-guidance-ui" >}} ) and any agents or
+backends for [Backends]( {{< ref "#backends" >}} ). While the navigation application
bundle may provide backends which feed data to a lot of the geo-APIs in
the SDK, it may additionally use a private connection and arbitrary
protocol to communicate between its backends and its UI. Data being
@@ -1293,7 +1293,7 @@ presented in the navigation application UI does not necessarily come
from SDK APIs. See [this non-use-case][SDK APIs for third-party navigation applications].
A system might not have a navigation application installed (see
-[][Navigation routing API]), in which case all APIs
+ [Navigation routing API]( {{< ref "#navigation-routing-api" >}} )), in which case all APIs
which depend on it must return suitable error codes.
### 2D map display
@@ -1407,7 +1407,7 @@ application and instruct it to calculate a new route. This API is the
[content hand-over] API, where the navigation application can be
launched using a nav URI. The nav URI scheme is a custom scheme (which
must not be confused with the standard [geo URI scheme], which is
-for identifying coordinates by latitude and longitude). See [][Appendix: nav URI scheme]
+for identifying coordinates by latitude and longitude). See [Appendix: nav URI scheme]( {{< ref "#appendix-nav-uri-scheme" >}} )
for a definition of the scheme, and examples.
When handling a content hand-over request, the navigation application
@@ -1430,7 +1430,7 @@ design.
### Navigation route list API
Separately from the content hand-over API for sending a destination to
-the navigation application (see [][Navigation routing]),
+the navigation application (see [Navigation routing]( {{< ref "#navigation-routing" >}} )),
there should be a navigation route list API to expose information about
the route geometry to SDK applications.
@@ -1438,7 +1438,7 @@ This API will be provided by the SDK, but implemented by one of many
backends — the navigation application will be one such backend, but
another backend will be available on the SDK to expose mock data for
testing applications against. The mock data will be provided by an
-emulator; see [][Testing applications] for more information.
+emulator; see [Testing applications]( {{< ref "#testing-applications" >}} ) for more information.
These backends will feed into a system service which provides the SDK
API to applications, and exposes:
@@ -1449,10 +1449,10 @@ API to applications, and exposes:
- Potential alternative routes.
The API will not expose the vehicle’s current position — that’s done by
-the [][Geolocation]. Similarly, it will not expose points
+the [Geolocation]( {{< ref "#geolocation" >}} ). Similarly, it will not expose points
of interest or other horizon data — that’s done by the
[points of interest API][Points of interest design]; or guidance information —
-that’s done by the [][Navigation route guidance API]).
+that’s done by the [Navigation route guidance API]( {{< ref "#navigation-route-guidance-api" >}} )).
The API should emit signals on changes of any of this information, using
the standard org.freedesktop.DBus.Properties signals. We recommend the
@@ -1578,7 +1578,7 @@ By using a combination of the navigation route guidance API and the
[points of interest API][Points of interest design], it should be possible for an OEM to
provide a route guidance UI which is separate from their main navigation
application UI, but which provides sufficient information for route
-guidance and display of points of interest, as described in [][Separate route guidance UI].
+guidance and display of points of interest, as described in [Separate route guidance UI]( {{< ref "#separate-route-guidance-ui" >}} ).
There is no need for a separate API for this, and it is expected that if
an OEM wishes to provide a route guidance UI, they can do so as a
@@ -1589,10 +1589,10 @@ system implements the route guidance D-Bus interfaces described above.
### Horizon API
-The [][Horizon] API is a shared library which
+The [Horizon]( {{< ref "#horizon" >}} ) API is a shared library which
applications are recommended to use when they want to present horizon
data in their UI — a combination of the route list and upcoming points
-of interest. The library should query the [][Navigation route list API]
+of interest. The library should query the [Navigation route list API]( {{< ref "#navigation-route-list-api" >}} )
and [points of interest APIs][Points of interest design]
and aggregate the results for display in the application. It is provided as a convenience and does not
implement functionality which applications could not otherwise implement
@@ -1664,7 +1664,7 @@ lists around the system. Key points illustrated are:
- If no navigation bundle is installed, the SDK route list service
still exists, it just returns no data.
-
+
### Forward and reverse geocoding
@@ -1760,7 +1760,7 @@ user’s home address, ‘work’ to their work address, and ‘here’ to the
vehicle’s current location. In order to maintain the confidentiality of
this data, applications must have permission to access the system
address book (containing the home and work addresses), and permission to
-access the vehicle’s location (see [][Location security]).
+access the vehicle’s location (see [Location security]( {{< ref "#location-security" >}} )).
If the application does not have appropriate permissions, the backend must not return
results for those queries.
@@ -1775,7 +1775,7 @@ from D-Bus requests in order to check permissions.
We recommend that GeoClue is modified upstream to implement geofencing
of arbitrary regions, meaning that geofencing becomes part of
-[][Geolocation]. Signals on entering or exiting a
+ [Geolocation]( {{< ref "#geolocation" >}} ). Signals on entering or exiting a
geofenced area should be emitted as a D-Bus signal which the application
subscribes to. Delivery of signals to bundles which are not currently
running may cause activation of that application.
@@ -1967,36 +1967,36 @@ stable and well defined.
This design fulfils the following requirements:
- - [][Geolocation API]
+ - [Geolocation API]( {{< ref "#geolocation-api" >}} )
— use GeoClue
- - [][Geolocation service supports signals]
+ - [Geolocation service supports signals]( {{< ref "#geolocation-service-supports-signals" >}} )
— use GeoClue; augment its signals
- - [][Geolocation implements caching]
+ - [Geolocation implements caching]( {{< ref "#geolocation-implements-caching" >}} )
— to be added to GeoClue
- - [][Geolocation supports backends]
+ - [Geolocation supports backends]( {{< ref "#geolocation-supports-backends" >}} )
— GeoClue supports backends
- - [][Navigation routing API]
+ - [Navigation routing API]( {{< ref "#navigation-routing-api" >}} )
— use content hand-over design, passing a nav URI to the navigation application
- - [][Navigation routing supports different navigation applications]
+ - [Navigation routing supports different navigation applications]( {{< ref "#navigation-routing-supports-different-navigation-applications" >}} )
— content hand-over supports setting different applications as the
handlers for the nav URI scheme
- - [][Navigation route list API]
+ - [Navigation route list API]( {{< ref "#navigation-route-list-api" >}} )
— new D-Bus API which is implemented by the navigation application backend
- - [][Navigation route guidance API]
+ - [Navigation route guidance API]( {{< ref "#navigation-route-guidance-api" >}} )
— new D-Bus API implemented by the system UI (i.e. the compositor) which is called by the
navigation application
- - [][Type-ahead search and address completion supports backends]
+ - [Type-ahead search and address completion supports backends]( {{< ref "#type-ahead-search-and-address-completion-supports-backends" >}} )
— implemented as part of geocoding, to be added to geocode-glib
- - [][Geocoding supports backends]
+ - [Geocoding supports backends]( {{< ref "#geocoding-supports-backends" >}} )
— to be added to geocode-glib
- [SDK has default implementations for all backends][SDK has default implementations for all backends]
@@ -2006,67 +2006,67 @@ This design fulfils the following requirements:
navigation route list; custom online Nominatim or Photon server for
address completion
- - [][SDK APIs do not vary with backend]
+ - [SDK APIs do not vary with backend]( {{< ref "#sdk-apis-do-not-vary-with-backend" >}} )
— GeoClue API for geolocation; geocode-glib for geocoding; libchamplain for 2D maps;
libnavit for 3D maps, **subject to further evaluation**; content
hand-over API for navigation routing; new API for navigation route
lists and guidance; new API extensions to geocode-glib for address
completion
- - [][Third-party navigation applications can be used as backends]
+ - [Third-party navigation applications can be used as backends]( {{< ref "#third-party-navigation-applications-can-be-used-as-backends" >}} )
— backends are implemented as loadable libraries installed by the
navigation application
- - [][Backends operate asynchronously]
+ - [Backends operate asynchronously]( {{< ref "#backends-operate-asynchronously" >}} )
— backends are implemented over D-Bus so are inherently asynchronous
- - [][2D map rendering API]
+ - [2D map rendering API]( {{< ref "#2d-map-rendering-api" >}} )
— use libchamplain with a local or remote tile store
- - [][2.5D or 3D map rendering API]
+ - [2.5D or 3D map rendering API]( {{< ref "#25d-or-3d-map-rendering-api" >}} )
— use libnavit, **subject to further evaluation**
- - [][Reverse geocoding API]
+ - [Reverse geocoding API]( {{< ref "#reverse-geocoding-api" >}} )
— use geocode-glib
- - [][Forward geocoding API]
+ - [Forward geocoding API]( {{< ref "#forward-geocoding-api" >}} )
— use geocode-glib
- - [][Type-ahead search and address completion API]
+ - [Type-ahead search and address completion API]( {{< ref "#type-ahead-search-and-address-completion-api" >}} )
— to be added to geocode-glib
- - [][Geofencing API]
+ - [Geofencing API]( {{< ref "#geofencing-api" >}} )
— to be implemented as a new feature in GeoClue
- - [][Geofencing service can wake up applications]
+ - [Geofencing service can wake up applications]( {{< ref "#geofencing-service-can-wake-up-applications" >}} )
— to be implemented as a new feature in GeoClue
- - [][Geofencing API signals on national borders]
+ - [Geofencing API signals on national borders]( {{< ref "#geofencing-api-signals-on-national-borders" >}} )
— to be added as a data set in GeoClue
- - [][Geocoding API must be locale aware]
+ - [Geocoding API must be locale aware]( {{< ref "#geocoding-api-must-be-locale-aware" >}} )
— to be added to geocode-glib to expose existing OpenStreetMap localised data
- - [][Geolocation provides error bounds]
+ - [Geolocation provides error bounds]( {{< ref "#geolocation-provides-error-bounds" >}} )
— GeoClue provides accuracy information, but it needs augmenting
- - [][Geolocation implements dead reckoning]
+ - [Geolocation implements dead reckoning]( {{< ref "#geolocation-implements-dead-reckoning" >}} )
— to be added to GeoClue
- - [][Geolocation uses navigation and sensor data if available]
+ - [Geolocation uses navigation and sensor data if available]( {{< ref "#geolocation-uses-navigation-and-sensor-data-if-available" >}} )
— to be added as another backend to GeoClue
- - [][General points of interest streams are queryable] — to be
+ - [General points of interest streams are queryable]( {{< ref "#general-points-of-interest-streams-are-queryable" >}} ) — to be
designed and implemented as part of the [points of interest design]
- - [][Location information requires permissions to access]
+ - [Location information requires permissions to access]( {{< ref "#location-information-requires-permissions-to-access" >}} )
— to be implemented as manifest permissions for application bundles
- - [][Rate limiting of general point of interest streams]
+ - [Rate limiting of general point of interest streams]( {{< ref "#rate-limiting-of-general-point-of-interest-streams" >}} )
— security boundary implemented as D-Bus API boundary; rate limiting applied on
signal emission and processed general point of interest streams
- - [][Application provided data requires permissions to create]
+ - [Application provided data requires permissions to create]( {{< ref "#application-provided-data-requires-permissions-to-create" >}} )
— all geo-services must check settings before accepting data from
applications
@@ -2093,8 +2093,8 @@ further in-depth design work, but should require fairly self-contained
changes.
The second phase also includes writing the new services, such as the
-[][Navigation route list API], the [][Navigation route guidance API]
-and the [][Horizon API].
+ [Navigation route list API]( {{< ref "#navigation-route-list-api" >}} ), the [Navigation route guidance API]( {{< ref "#navigation-route-guidance-api" >}} )
+and the [Horizon API]( {{< ref "#horizon-api" >}} ).
## Open questions
@@ -2398,7 +2398,7 @@ i.e. each parameter is separated by a semicolon, keys and values are separated b
an equals sign, and percent-encoding is used to encode reserved
characters.
-The destination place must be provided as [][Appendix: place URI scheme]
+The destination place must be provided as [Appendix: place URI scheme]( {{< ref "#appendix-place-uri-scheme" >}} )
(*with* the `place:` URI prefix), or as a geo URI (*with* the `geo:` URI prefix); and
must be encoded in the format `1\*paramchar`, as defined in RFC 5870; i.e.
all non-ASCII and reserved characters in the string must be
diff --git a/content/designs/global-search.md b/content/designs/global-search.md
index 6be4252f621480d03ed2183b9a3f6459769006a1..adfac7431d0d266332e347b2a36ef90e06baad93 100644
--- a/content/designs/global-search.md
+++ b/content/designs/global-search.md
@@ -286,7 +286,7 @@ back-ends to produce their search results. Each source has a plug-in
specifically written to process a certain kind of data and return
standardized search results.
-> [][Using existing global search software]
+> [Using existing global search software]( {{< ref "#using-existing-global-search-software" >}} )
> provides details on some existing global search solutions.
Allowing applications to be responsible for providing search results on
@@ -357,7 +357,7 @@ that the appropriate data is immediately displayed. The application
manager and the application will have to negotiate this launch.
Searching the persistence API's storage is covered further in
-[][The SDK persistence API].
+ [The SDK persistence API]( {{< ref "#the-sdk-persistence-api" >}} ).
### Highly Responsive
@@ -494,7 +494,7 @@ available, others don't yet have a free implementation or are Apertis
specific.
-> [][New software development] later in this document is
+> [New software development]( {{< ref "#new-software-development" >}} ) later in this document is
> intended to give an overview of what suggested components would
> require new software development.
@@ -590,7 +590,7 @@ Data should be stored in such a way that the search result can be easily
passed to the appropriate application for launching. One possible set of
data for an item stored by the persistence API would be:
- - The information classification (as in [][Information classification])
+ - The information classification (as in [Information classification]( {{< ref "#information-classification" >}} ))
for the stored item.
- The name of the item – the name of the web page a bookmark refers
@@ -653,7 +653,7 @@ A search begins in the HMI, either by voice recognition or by
interaction with the touch screen. Before any lengthy search is
performed, hard coded response logic is checked for simple responses
such as changing the radio station or checking the weather at the
-current location.
+current location.
If this logic completes the search, the appropriate action is taken and
the interface is dismissed. If there is no user selection within a
@@ -692,7 +692,7 @@ decisions, such as file formats or storage methods for application data
(like bookmarks, calendar entries, and contact information.)
However, this section provides some potential ways to provide search
-results for each of the content types from [][Content categories]
+results for each of the content types from [Content categories]( {{< ref "#content-categories" >}} )
and some recommendations that may make developing the search
system easier.
@@ -878,7 +878,7 @@ results, a method of selecting which lens to search with would also be
required. In the Unity Dash this is known as the “lens barâ€.
A set of Lenses are required, one for each type of searchable data – the
-list of content categories from [][Content categories] would provide a
+list of content categories from [Content categories]( {{< ref "#content-categories" >}} ) would provide a
good selection of lenses. Some of the lenses already available for Unity
might fill these roles.
@@ -903,7 +903,7 @@ To implement a global search interface like the one described in this
document, new software components will need to be created:
- A plug-in framework for integrating search back-ends, perhaps built
- on or with code re-used from software from [][Using existing global search software]
+ on or with code re-used from software from [Using existing global search software]( {{< ref "#using-existing-global-search-software" >}} )
A similar plugin framework is also offered
by Grilo. Although Grilo is focused on multimedia content, the
plugin framework could be reused and adapted to serve general
@@ -911,7 +911,7 @@ document, new software components will need to be created:
already used within Apertis, avoiding new dependencies.
- Plug-ins for the framework – many of these will be thin wrappers
- around existing search functionality such as that listed in [][Potential search back-ends],
+ around existing search functionality such as that listed in [Potential search back-ends]( {{< ref "#potential-search-back-ends" >}} ),
some will be Apertis specific and require more development.
- A UI for presenting and interacting with search results.
diff --git a/content/designs/hardkeys.md b/content/designs/hardkeys.md
index fd93f388df36980370a7ccc561eb1f654fba875b..0e1ca043e125879ffa1a3794ca6aa11babe280f8 100644
--- a/content/designs/hardkeys.md
+++ b/content/designs/hardkeys.md
@@ -121,7 +121,7 @@ various sources and chooses how to handle them. The diagram below has a
high-level overview of some example input sources and examples of the
various types of controls.
-
+
Thanks to the Wayland input flow only having two actors (the compositor
and the receiver) (as opposed to that of X11) that there is no way for
diff --git a/content/designs/inter-domain-communication.md b/content/designs/inter-domain-communication.md
index 11df736e07ccd88333160c6d3881f3b13285fa88..3d21285caba21d2e55e6751cb1d50a9d1cb4385a 100644
--- a/content/designs/inter-domain-communication.md
+++ b/content/designs/inter-domain-communication.md
@@ -132,7 +132,7 @@ communication system are given below. Particularly important discussion
points are highlighted at the bottom of each use case.
All of these use cases are relevant to an inter-domain communication
-system, but some of them (for example, [][Video or audio decoder bugs]) may equally well be
+system, but some of them (for example, [Video or audio decoder bugs]( {{< ref "#video-or-audio-decoder-bugs" >}} )) may equally well be
solved by other components in the system.
### Standalone setup
@@ -395,7 +395,7 @@ decoding of trusted or untrusted video content. This is high bandwidth,
but means that the output from the video decoder could potentially be
directed straight onto a surface on the screen.
-(See [][Appendix: Audio and video decoding] for a discussion of options for video and audio
+(See [Appendix: Audio and video decoding]( {{< ref "#appendix-audio-and-video-decoding" >}} ) for a discussion of options for video and audio
decoding.)
#### Video or audio decoder bugs
@@ -579,7 +579,7 @@ than remaining unanswered indefinitely.
The same situation applies if both domains are booting simultaneously,
but the CE is slower to boot than the AD, for example — the AD will be
up before the CE, and hence must deal with not being able to communicate
-with it. See also [][Plug-and-play CE device].
+with it. See also [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} ).
### Power cycle independence of domains (AD down, single screen)
@@ -595,7 +595,7 @@ than remaining unanswered indefinitely.
The same situation applies if both domains are booting simultaneously,
but the AD is slower to boot than the CE, for example — the CE will be
up before the AD, and hence must deal with not being able to communicate
-with it. See also [][Plug-and-play CE device].
+with it. See also [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} ).
### Power cycle independence of domains (AD down, multiple screens)
@@ -613,7 +613,7 @@ than remaining unanswered indefinitely.
The same situation applies if both domains are booting simultaneously,
but the AD is slower to boot than the CE, for example — the CE will be
up before the AD, and hence must deal with not being able to communicate
-with it. See also [][Plug-and-play CE device].
+with it. See also [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} ).
### Temporary communications problem
@@ -644,7 +644,7 @@ continues longer than a timeout, the domains must assume that each other
have crashed and behave accordingly.
If a domain has crashed, the other domain must wait for it to be
-restarted via its watchdog, as in [][Power cycle independence of domains (CE down)].
+restarted via its watchdog, as in [Power cycle independence of domains (CE down)]( {{< ref "#power-cycle-independence-of-domains-ce-down" >}} ).
In all cases, the domain which is still running must not shut down or
enter a ‘paused’ state, as that would allow denial of service attacks.
@@ -675,7 +675,7 @@ operating system, and a tweaked version 15.06 of Apertis.
In other words, this scenario applies only when the OEM has updated the
AD, and wants to make a corresponding update to the CE. For the reverse
scenario where the CE has been upgraded, it is required that the AD does
-not need to be updated: see [][Plug-and-play CE device] and [][After market CE upgrades].
+not need to be updated: see [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} ) and [After market CE upgrades]( {{< ref "#after-market-ce-upgrades" >}} ).
### Unsupported AD interfaces
@@ -805,9 +805,9 @@ dashboard by the user, and passed around the car so that, for example, a
rear seat passenger could play a game. This disconnects it from the AD,
but it should continue to function with some features (such as Wi-Fi or
Bluetooth) disabled until it is reconnected. Once reconnected to the
-dashboard it should reestablish its connections. See also, [][Power cycle independence of domains (CE down)],
-[][Power cycle independence of domains (AD down, single screen)],
-[][Power cycle independence of domains (AD down, multiple screens)]
+dashboard it should reestablish its connections. See also, [Power cycle independence of domains (CE down)]( {{< ref "#power-cycle-independence-of-domains-ce-down" >}} ),
+ [Power cycle independence of domains (AD down, single screen)]( {{< ref "#power-cycle-independence-of-domains-ad-down-single-screen" >}} ),
+ [Power cycle independence of domains (AD down, multiple screens)]( {{< ref "#power-cycle-independence-of-domains-ad-down-multiple-screens" >}} )
*(Note: This is a much lower priority than other setups, but should
still be considered as part of the overall design, even if the code for
@@ -872,7 +872,7 @@ for this.
#### Passenger
-The passenger is a special kind of third party attacker ([][Third parties]),
+The passenger is a special kind of third party attacker ( [Third parties]( {{< ref "#third-parties" >}} )),
who additionally has access to the in-vehicle network. This may be
possible if, for example, the Apertis device in the vehicle is removable
so it can be passed to a passenger, exposing a connector behind it.
@@ -1047,21 +1047,21 @@ Support a configuration where the CE is running in a virtual machine
with the Apertis SDK, so the peer (which would normally be the AD) is a
mock AD daemon running against the SDK.
-See [][Standalone setup].
+See [Standalone setup]( {{< ref "#standalone-setup" >}} ).
#### Transport over virtio
Support a configuration where the CE and AD communicate over a virtio
link between two virtual machines under a hypervisor.
-See [][Basic virtualised setup].
+See [Basic virtualised setup]( {{< ref "#basic-virtualised-setup" >}} ).
#### Transport over a private Ethernet link
Support a configuration where the CE and AD are on separate CPUs and
communicate over a point-to-point Ethernet link.
-See [][Separate CPUs setup], [][Separate boards setup].
+See [Separate CPUs setup]( {{< ref "#separate-cpus-setup" >}} ), [Separate boards setup]( {{< ref "#separate-boards-setup" >}} ).
#### Transport over a private Ethernet link to a development vehicle
@@ -1069,14 +1069,14 @@ Support a configuration where the CE is running in an SDK on a laptop,
and the AD is running in a developer-mode Apertis device in a vehicle,
and the two communicate over a wider shared Ethernet.
-See [][Connecting an SDK to a development vehicle].
+See [Connecting an SDK to a development vehicle]( {{< ref "#connecting-an-sdk-to-a-development-vehicle" >}} ).
#### Transport over a shared Ethernet link
Support a configuration where the CE and AD are on separate CPUs are are
both connected to some wider shared Ethernet.
-See [][Separate boards setup with other devices], [][Multiple CE domains setup].
+See [Separate boards setup with other devices]( {{< ref "#separate-boards-setup-with-other-devices" >}} ), [Multiple CE domains setup]( {{< ref "#multiple-ce-domains-setup" >}} ).
#### Transport over Unix Domain Socket
@@ -1084,7 +1084,7 @@ Support a configuration where AD and CE are on the same host running as
Linux containers and connected via UDS. The same transport can be used on
OEM deployments and on SDK environments.
-See [][Linux container setup], [][Multiple CE domains setup].
+See [Linux container setup]( {{< ref "#linux-container-setup" >}} ), [Multiple CE domains setup]( {{< ref "#multiple-ce-domains-setup" >}} ).
### Message integrity and confidentiality in transport layer
@@ -1092,9 +1092,9 @@ Some of the possible physical links between domains do not guarantee
integrity or confidentiality of messages, so these must be implemented
in the software transport layer.
-See [][Separate CPUs setup], [][Separate boards setup],
-[][Separate boards setup with other devices], [][Multiple CE domains setup],
-[][Wi-Fi access].
+See [Separate CPUs setup]( {{< ref "#separate-cpus-setup" >}} ), [Separate boards setup]( {{< ref "#separate-boards-setup" >}} ),
+ [Separate boards setup with other devices]( {{< ref "#separate-boards-setup-with-other-devices" >}} ), [Multiple CE domains setup]( {{< ref "#multiple-ce-domains-setup" >}} ),
+ [Wi-Fi access]( {{< ref "#wi-fi-access" >}} ).
### Reliability and error checking in transport layer
@@ -1102,8 +1102,8 @@ Some of the possible physical links between domains do not guarantee
reliable or error-free transfer of messages, so these must be
implemented in the software transport layer.
-See [][Separate boards setup], [][Separate boards setup with other devices],
-[][Multiple CE domains setup].
+See [Separate boards setup]( {{< ref "#separate-boards-setup" >}} ), [Separate boards setup with other devices]( {{< ref "#separate-boards-setup-with-other-devices" >}} ),
+ [Multiple CE domains setup]( {{< ref "#multiple-ce-domains-setup" >}} ).
### Mutual authentication between domains
@@ -1112,7 +1112,7 @@ attempt to impersonate the AD to the CE, or the CE to the AD. The
domains must mutually authenticate before accepting any messages from
each other.
-See [][Tinkering vehicle owner on the network].
+See [Tinkering vehicle owner on the network]( {{< ref "#tinkering-vehicle-owner-on-the-network" >}} ).
### Separate authentication for developer and production mode devices
@@ -1121,8 +1121,8 @@ an AD running in a vehicle which is in a special ‘developer mode’. If
the same CE is connected to a production vehicle, it must not be able to
connect and authenticate.
-See [][Connecting an SDK to a development vehicle],
-[][Connecting an SDK to a production vehicle].
+See [Connecting an SDK to a development vehicle]( {{< ref "#connecting-an-sdk-to-a-development-vehicle" >}} ),
+ [Connecting an SDK to a production vehicle]( {{< ref "#connecting-an-sdk-to-a-production-vehicle" >}} ).
### Individually addressed domains
@@ -1131,7 +1131,7 @@ domain, each domain (consumer–electronics and automotive) must be
individually addressable. The system must not assume that there are only
two domains in the network.
-See [][Multiple CE domains setup].
+See [Multiple CE domains setup]( {{< ref "#multiple-ce-domains-setup" >}} ).
### Traffic control for latency
@@ -1141,7 +1141,7 @@ must guarantee a low latency for all communications, or provide a
traffic control system to allow certain messages (for example,
touchscreen messages) to have a guaranteed latency.
-See [][Touchscreen events].
+See [Touchscreen events]( {{< ref "#touchscreen-events" >}} ).
### Traffic control for bandwidth
@@ -1154,7 +1154,7 @@ definition).
This may be implemented by separating ‘control’ and ‘data’ streams (see
sections 2.4 and 2.5), or by applying traffic control algorithms.
-See [][Wi-Fi access], [][Bluetooth access].
+See [Wi-Fi access]( {{< ref "#wi-fi-access" >}} ), [Bluetooth access]( {{< ref "#bluetooth-access" >}} ).
### Traffic control for frequency
@@ -1168,7 +1168,7 @@ bandwidth requirements; but if the inter-domain link saturates at
100000KB per second, some of the messages from service A must be delayed
or dropped as the messaging overheads exceed the bandwidth limit.
-See [][Denial of service through flooding].
+See [Denial of service through flooding]( {{< ref "#denial-of-service-through-flooding" >}} ).
### Separation of control and data streams
@@ -1178,7 +1178,7 @@ must support multiple streams; this may be via an explicit separation
between ‘control’ and ‘data’ streams, or by applying traffic control
algorithms.
-See [][Wi-Fi access], [][Bluetooth access], [][Audio transfer], [][Video decoding].
+See [Wi-Fi access]( {{< ref "#wi-fi-access" >}} ), [Bluetooth access]( {{< ref "#bluetooth-access" >}} ), [Audio transfer]( {{< ref "#audio-transfer" >}} ), [Video decoding]( {{< ref "#video-decoding" >}} ).
### No untrusted access to AD hardware
@@ -1201,8 +1201,8 @@ Note that it is not possible to check audio or video content for
‘badness’ before sending it to a decoder, as that entails doing the
full decoding process anyway.
-See [][Audio transfer], [][Video decoding], [][Video or audio decoder bugs],
-[][Connecting an SDK to a production vehicle].
+See [Audio transfer]( {{< ref "#audio-transfer" >}} ), [Video decoding]( {{< ref "#video-decoding" >}} ), [Video or audio decoder bugs]( {{< ref "#video-or-audio-decoder-bugs" >}} ),
+ [Connecting an SDK to a production vehicle]( {{< ref "#connecting-an-sdk-to-a-production-vehicle" >}} ).
### Trusted path for users to update the CE operating system
@@ -1214,8 +1214,8 @@ must always have access to this update system (it must always be
This trusted path may also be used by garages to upgrade the CE when
servicing a vehicle; or a different path may be used.
-See [][Video or audio decoder bugs], [][After market CE upgrades],
-[][Malicious CE UI].
+See [Video or audio decoder bugs]( {{< ref "#video-or-audio-decoder-bugs" >}} ), [After market CE upgrades]( {{< ref "#after-market-ce-upgrades" >}} ),
+ [Malicious CE UI]( {{< ref "#malicious-ce-ui" >}} ).
### Safety limits on AD APIs
@@ -1230,7 +1230,7 @@ implementations. It might not be possible to detect all unsafe
situations (in the sense of an unsafe situation which could lead to an
accident).
-See [][Tinkering vehicle owner on the boards], [][Malicious CE].
+See [Tinkering vehicle owner on the boards]( {{< ref "#tinkering-vehicle-owner-on-the-boards" >}} ), [Malicious CE]( {{< ref "#malicious-ce" >}} ).
### Rate limiting on control messages
@@ -1243,7 +1243,7 @@ This should be in addition to rate limiting implemented in the SDK APIs
in the CE themselves, which are expected to be the first line of defence
against denial of service attacks.
-See [][Denial of service through flooding].
+See [Denial of service through flooding]( {{< ref "#denial-of-service-through-flooding" >}} ).
### Ignore unrecognised messages
@@ -1253,7 +1253,7 @@ expects a reply, an error reply must be sent. The domains must not, for
example, shut down or crash when receiving an unrecognised message, as
that would lead to a denial of service vulnerability.
-See [][Tinkering vehicle owner on the boards], [][Malicious CE].
+See [Tinkering vehicle owner on the boards]( {{< ref "#tinkering-vehicle-owner-on-the-boards" >}} ), [Malicious CE]( {{< ref "#malicious-ce" >}} ).
### Portable transport layer
@@ -1263,7 +1263,7 @@ operating systems. This means, for example, that it must not depend on
features added to very recent versions of the Linux kernel, or must have
fallback implementations for them.
-See [][Support multiple AD operating systems].
+See [Support multiple AD operating systems]( {{< ref "#support-multiple-ad-operating-systems" >}} ).
### Support push mode and pull mode communications
@@ -1272,7 +1272,7 @@ it makes a method call and receives a reply; and push mode
communications, where the AD emits a signal for an event, and the CE
receives this.
-See [][Support multiple AD operating systems].
+See [Support multiple AD operating systems]( {{< ref "#support-multiple-ad-operating-systems" >}} ).
### OEM AD integration API
@@ -1284,7 +1284,7 @@ over the inter-domain communication link.
This API must support an implementation which uses the services in the
Apertis SDK.
-See [][Support multiple AD operating systems], [][Standalone setup].
+See [Support multiple AD operating systems]( {{< ref "#support-multiple-ad-operating-systems" >}} ), [Standalone setup]( {{< ref "#standalone-setup" >}} ).
### Flexibility in OEM AD integration API
@@ -1296,8 +1296,8 @@ which is not currently supported by any CE. This functionality should be
exposed on the inter-domain communications link, in case future versions
of the CE can take advantage of it.
-See [][Support multiple AD operating systems], [][Before market CE upgrades],
-[][After market CE upgrades], [][New version of AD software], [][New version of AD interfaces].
+See [Support multiple AD operating systems]( {{< ref "#support-multiple-ad-operating-systems" >}} ), [Before market CE upgrades]( {{< ref "#before-market-ce-upgrades" >}} ),
+ [After market CE upgrades]( {{< ref "#after-market-ce-upgrades" >}} ), [New version of AD software]( {{< ref "#new-version-of-ad-software" >}} ), [New version of AD interfaces]( {{< ref "#new-version-of-ad-interfaces" >}} ).
### Inflexibility in OEM AD integration API
@@ -1305,7 +1305,7 @@ The OEM AD integration API must not allow access to arbitrary services
or APIs on the AD. It must only allow access to the services and APIs
explicitly exposed by the OEM in their use of the integration API.
-See [][Unsupported AD interfaces].
+See [Unsupported AD interfaces]( {{< ref "#unsupported-ad-interfaces" >}} ).
### Service discovery
@@ -1326,8 +1326,8 @@ If the protocol uses versioning to add new features, both domains must
support protocol version negotiation to find a version which is
supported if the latest one is not.
-See [][Before market CE upgrades], [][After market CE upgrades],
-[][New version of AD software], [][Unsupported AD interfaces], [][Protocol compatibility].
+See [Before market CE upgrades]( {{< ref "#before-market-ce-upgrades" >}} ), [After market CE upgrades]( {{< ref "#after-market-ce-upgrades" >}} ),
+ [New version of AD software]( {{< ref "#new-version-of-ad-software" >}} ), [Unsupported AD interfaces]( {{< ref "#unsupported-ad-interfaces" >}} ), [Protocol compatibility]( {{< ref "#protocol-compatibility" >}} ).
### Testability of protocols
@@ -1338,7 +1338,7 @@ must be testable without running an automotive domain; the link between
SDK API services and the inter-domain interface at the boundary of the
CE domain must be testable without running an automotive domain; etc.
-See [][Testability], [][New version of AD software], [][Unsupported AD interfaces].
+See [Testability]( {{< ref "#testability" >}} ), [New version of AD software]( {{< ref "#new-version-of-ad-software" >}} ), [Unsupported AD interfaces]( {{< ref "#unsupported-ad-interfaces" >}} ).
### Testability of protocol parsers and writers
@@ -1350,7 +1350,7 @@ example, if a protocol requires a certificate to authenticate a peer, a
test must be included which attempts a connection with different types
of invalid certificate.
-See [][Testability], [][New version of AD software], [][Unsupported AD interfaces].
+See [Testability]( {{< ref "#testability" >}} ), [New version of AD software]( {{< ref "#new-version-of-ad-software" >}} ), [Unsupported AD interfaces]( {{< ref "#unsupported-ad-interfaces" >}} ).
### Testability of processes
@@ -1362,7 +1362,7 @@ well defined and documented API, and then using that library in a
trivial wrapper program which hooks it up to input and output streams
and accepts command line arguments.
-See [][Testability], [][New version of AD software], [][Unsupported AD interfaces].
+See [Testability]( {{< ref "#testability" >}} ), [New version of AD software]( {{< ref "#new-version-of-ad-software" >}} ), [Unsupported AD interfaces]( {{< ref "#unsupported-ad-interfaces" >}} ).
### CE system services separated from transport layer
@@ -1379,7 +1379,7 @@ A, rather than to impersonate all services in the CE. It also allows the
resource usage of the inter-domain service to be limited, to limit the
impact of a denial of service attack on it.
-See [][Malicious CE], [][Marshalling resource usage].
+See [Malicious CE]( {{< ref "#malicious-ce" >}} ), [Marshalling resource usage]( {{< ref "#marshalling-resource-usage" >}} ).
### No dependency on CE specific hardware
@@ -1395,7 +1395,7 @@ This requirement may also be satisfied by including provisions for
updating the copy of a key in the AD if such a dependency on a specific
CE key is a sensible implementation choice.
-See [][After market upgrade of a domain].
+See [After market upgrade of a domain]( {{< ref "#after-market-upgrade-of-a-domain" >}} ).
### Immediate error response if service on peer is unavailable
@@ -1406,10 +1406,10 @@ should propagate it to any caller of SDK APIs which use the failing
service. An error response must be returned, otherwise the caller will
time out.
-See [][Power cycle independence of domains (CE down)],
-[][Power cycle independence of domains (AD down, single screen)],
-[][Power cycle independence of domains (AD down, multiple screens)],
-[][Plug-and-play CE device]
+See [Power cycle independence of domains (CE down)]( {{< ref "#power-cycle-independence-of-domains-ce-down" >}} ),
+ [Power cycle independence of domains (AD down, single screen)]( {{< ref "#power-cycle-independence-of-domains-ad-down-single-screen" >}} ),
+ [Power cycle independence of domains (AD down, multiple screens)]( {{< ref "#power-cycle-independence-of-domains-ad-down-multiple-screens" >}} ),
+ [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} )
### Immediate error response if peer is unavailable
@@ -1420,10 +1420,10 @@ in the inter-domain service and return that to any caller of SDK APIs
which require inter-domain communications. An error response must be
returned, otherwise the caller will time out.
-See [][Power cycle independence of domains (CE down)],
-[][Power cycle independence of domains (AD down, single screen)],
-[][Power cycle independence of domains (AD down, multiple screens)],
-[][Plug-and-play CE device]
+See [Power cycle independence of domains (CE down)]( {{< ref "#power-cycle-independence-of-domains-ce-down" >}} ),
+ [Power cycle independence of domains (AD down, single screen)]( {{< ref "#power-cycle-independence-of-domains-ad-down-single-screen" >}} ),
+ [Power cycle independence of domains (AD down, multiple screens)]( {{< ref "#power-cycle-independence-of-domains-ad-down-multiple-screens" >}} ),
+ [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} )
### Timeout error response if peer does not respond
@@ -1434,10 +1434,10 @@ inter-domain communications. An error response must be returned,
otherwise the caller will wait for a response indefinitely (or have to
implement its own timeout logic, which would be redundant).
-See [][Power cycle independence of domains (CE down)],
-[][Power cycle independence of domains (AD down, single screen)],
-[][Power cycle independence of domains (AD down, multiple screens)],
-[][Plug-and-play CE device]
+See [Power cycle independence of domains (CE down)]( {{< ref "#power-cycle-independence-of-domains-ce-down" >}} ),
+ [Power cycle independence of domains (AD down, single screen)]( {{< ref "#power-cycle-independence-of-domains-ad-down-single-screen" >}} ),
+ [Power cycle independence of domains (AD down, multiple screens)]( {{< ref "#power-cycle-independence-of-domains-ad-down-multiple-screens" >}} ),
+ [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} )
### All inter-domain communications APIs are asynchronous
@@ -1452,7 +1452,7 @@ This encourages UIs to be written to not block on SDK API calls which
might take multiple seconds to complete, as during that time, the UI
would not be redrawn at all, and hence would appear to ‘freeze’.
-See [][Temporary communications problem].
+See [Temporary communications problem]( {{< ref "#temporary-communications-problem" >}} ).
### Reconnect to peer as soon as it is available
@@ -1462,7 +1462,7 @@ reconnect to its peer as soon as the peer can be found on the network.
If, for example, both domains had crashed, this may involve waiting for
the peer to connect to the network itself.
-See [][Plug-and-play CE device].
+See [Plug-and-play CE device]( {{< ref "#plug-and-play-ce-device" >}} ).
### External domain watchdog
@@ -1472,9 +1472,9 @@ restart them if they crash and fail to restart themselves.
The watchdog must be external, rather than being the other domain, in
case both domains crash at the same time.
-See [][Power cycle independence of domains (CE down)],
-[][Power cycle independence of domains (AD down, single screen)],
-[][Power cycle independence of domains (AD down, multiple screens)].
+See [Power cycle independence of domains (CE down)]( {{< ref "#power-cycle-independence-of-domains-ce-down" >}} ),
+ [Power cycle independence of domains (AD down, single screen)]( {{< ref "#power-cycle-independence-of-domains-ad-down-single-screen" >}} ),
+ [Power cycle independence of domains (AD down, multiple screens)]( {{< ref "#power-cycle-independence-of-domains-ad-down-multiple-screens" >}} ).
### Reporting system for malicious applications
@@ -1488,7 +1488,7 @@ to detect error responses from the AD which indicate that malicious
behaviour has been detected and rejected, and must be able to forward
those notifications to the reporting system.
-See [][Feedback for malicious applications].
+See [Feedback for malicious applications]( {{< ref "#feedback-for-malicious-applications" >}} ).
### Ability to disable the consumer–electronics domain
@@ -1499,7 +1499,7 @@ taking the vehicle to a trusted dealer to install an update.
As well as preventing booting the CE, this must disable all inter-domain
communications from within the inter-domain service in the AD.
-See [][Compromised CE with delayed fix].
+See [Compromised CE with delayed fix]( {{< ref "#compromised-ce-with-delayed-fix" >}} ).
### Tamper evidence
@@ -1510,8 +1510,8 @@ or hardware was modified — although it might not be possible for them to
determine *how* it was modified. This will allow for liability to be
attributed in the event of an accident or warranty claim.
-See [][Tinkering vehicle owner on the network],
-[][Tinkering vehicle owner on the boards].
+See [Tinkering vehicle owner on the network]( {{< ref "#tinkering-vehicle-owner-on-the-network" >}} ),
+ [Tinkering vehicle owner on the boards]( {{< ref "#tinkering-vehicle-owner-on-the-boards" >}} ).
### No global keys in vehicles
@@ -1524,8 +1524,8 @@ This means that if an attacker manages to compromise one vehicle, they
must not be able to learn anything (any keys) which would allow them to
compromise another vehicle with less effort.
-See [][Tinkering vehicle owner on the network],
-[][Tinkering vehicle owner on the boards].
+See [Tinkering vehicle owner on the network]( {{< ref "#tinkering-vehicle-owner-on-the-network" >}} ),
+ [Tinkering vehicle owner on the boards]( {{< ref "#tinkering-vehicle-owner-on-the-boards" >}} ).
## Existing inter-domain communication systems
@@ -1542,7 +1542,7 @@ against?
## Approach
-Based on the [above research][Existing domain communications system] and [][Requirements], we
+Based on the [above research][Existing domain communications system] and [Requirements]( {{< ref "#requirements" >}} ), we
recommend the following approach as an initial sketch of an inter-domain
communication system.
@@ -1551,32 +1551,32 @@ communication system.
In the following figure, each box represents a process, and hence each connection
between them is a trust boundary.
-
+
> Apertis IDC architecture. The ‘OEM specific’ APIs are also known as ‘native OEM APIs’;
> and the ‘OEM API’ is also known as the ‘Apertis automotive API’.
-> For more information on the export and adapter layer, see [][Automotive domain export layer]
-> and [][Consumer-electronics domain adapter layer].
+> For more information on the export and adapter layer, see [Automotive domain export layer]( {{< ref "#automotive-domain-export-layer" >}} )
+> and [Consumer-electronics domain adapter layer]( {{< ref "#consumer-electronics-domain-adapter-layer" >}} ).
APIs from the automotive domain are exported by an *export layer*
-([][Automotive domain export layer]) as D-Bus objects on the inter-domain communications link.
+( [Automotive domain export layer]( {{< ref "#automotive-domain-export-layer" >}} )) as D-Bus objects on the inter-domain communications link.
This link runs a known version of the D-Bus protocol (and requires
backwards compatibility indefinitely) between an *inter-domain service*
-process in each domain ([][Protocol library and inter-domain services]). The inter-domain service in the CE
+process in each domain ( [Protocol library and inter-domain services]( {{< ref "#protocol-library-and-inter-domain-services" >}} )). The inter-domain service in the CE
domain sends and receives D-Bus messages for the objects exported by the
automotive domain, and proxies them to a private bus in the CE domain.
SDK services in the CE domain connect to this bus, and an *adapter
-layer* [][Consumer-electronics domain adapter layer]
+layer* [Consumer-electronics domain adapter layer]( {{< ref "#consumer-electronics-domain-adapter-layer" >}} )
in each service converts the APIs from the
automotive domain to the SDK APIs used in the version of Apertis in use
in the CE domain. These SDK APIs are exported onto the normal D-Bus
-session bus, to be used by applications ([][Flow for a given SDK API call]).
+session bus, to be used by applications ( [Flow for a given SDK API call]( {{< ref "#flow-for-a-given-sdk-api-call" >}} )).
The export layer and adapter layer provide abstraction of the APIs from
the automotive domain: the export layer converts them from C APIs, QNX
message passing, or however they are implemented in the automotive OS,
to a D-Bus API which is specific to that OEM, but which has stability
-guarantees through use of API versioning ([][Interaction of the export and adapter layers]).
+guarantees through use of API versioning ( [Interaction of the export and adapter layers]( {{< ref "#interaction-of-the-export-and-adapter-layers" >}} )).
The adapter layer converts from this D-Bus API to the current version of the Apertis
SDK APIs. Both layers are OEM-specific.
@@ -1586,9 +1586,9 @@ be remarshalled — messages only need their headers to be changed before
they are forwarded. This should eliminate a common cause of poor
performance (remarshalling).
-High-bandwidth [][Data connections] are provided in
+High-bandwidth [Data connections]( {{< ref "#data-connections" >}} ) are provided in
parallel with the *control connection* which runs this D-Bus protocol
-([][Control protocol]). They use TCP, UDP or Unix sockets, and are opened between the two
+( [Control protocol]( {{< ref "#control-protocol" >}} )). They use TCP, UDP or Unix sockets, and are opened between the two
inter-domain services on request. Applications and services must define
their own protocols for communicating over these links, which are
appropriate to the data being transferred (for example, audio data or a
@@ -1597,14 +1597,14 @@ Bluetooth file transfer).
Authentication, confidentiality and integrity of all inter-domain
communications (the control connection and data connections) are
provided by using IPsec as the bottom layer of the protocol stack
-([][Encryption]). The same protocol stack is used for all configurations
+( [Encryption]( {{< ref "#encryption" >}} )). The same protocol stack is used for all configurations
of the two domains (from a standalone CE domain through to multiple CE
domains on a shared network with an automotive domain), to ensure that
the same code path is used for all configurations and hence is widely
-tested ([][Configuration designs]).
+tested ( [Configuration designs]( {{< ref "#configuration-designs" >}} )).
Addressing and discovery of domains, before the initial connection
-between them, is provided by IPv6 neighbour discovery ([][Traffic control]).
+between them, is provided by IPv6 neighbour discovery ( [Traffic control]( {{< ref "#traffic-control" >}} )).
Traffic control is implemented in the CE domain using standard Linux
kernel traffic control mechanisms, with the policy specified by the
@@ -1612,14 +1612,14 @@ inter-domain service (section 8.4). It is applied for the control
connection and for each data connection separately, as they are all
separate TCP or UDP connections.
-The only exception from the above is [][Linux container setup]
+The only exception from the above is [Linux container setup]( {{< ref "#linux-container-setup" >}} )
which uses Unix Domain Sockets as a trusted and reliable bottom transport layer
instead of IPsec. In this case, there is no need for traffic control.
-Addressing and discovery of local domains in [][Linux container setup] is
+Addressing and discovery of local domains in [Linux container setup]( {{< ref "#linux-container-setup" >}} ) is
based on common directories created and shared outside of the containers by
the container manager.
-
+
> Responsibilities for areas of code in the IDC architecture
@@ -1635,7 +1635,7 @@ process in the system.
isolated from other components to reduce the attack surface exposed
by the AD.
- - Rest of the automotive domain: as mentioned in [][Security domains], the
+ - Rest of the automotive domain: as mentioned in [Security domains]( {{< ref "#security-domains" >}} ), the
automotive domain is essentially a black box.
- Each application sandbox in the consumer–electronics domain.
@@ -1663,13 +1663,13 @@ authentication of peers, confidentiality of data and integrity of data.
In addition, the control plane must have bi-directional, in-order
transmission, framing, reliability and error detection. Conversely, the
data plane must have multiplexing, and the ability to apply traffic
-control to each of its connections ([][Traffic control]).
+control to each of its connections ( [Traffic control]( {{< ref "#traffic-control" >}} )).
The control plane is used for sending control data between the domains —
these are the method calls which form the majority of inter-domain
communications. They require low latency, and are low bandwidth. The
[control protocol][Control protocol] itself provides push and pull method
-call semantics, and allows for new data connections ([][Data connections]) to
+call semantics, and allows for new data connections ( [Data connections]( {{< ref "#data-connections" >}} )) to
be opened. Only one control connection exists between a pair of domains,
and it is always connected.
@@ -1693,7 +1693,7 @@ hierarchy, and implements addressing, routing, mutual authentication,
confidentiality and integrity for *all* connections in the control and
data planes.
-
+
> Protocol stacks for control and data planes if using IPsec.
@@ -1712,7 +1712,7 @@ both the AD and CE kernels. Some automotive operating systems may not
support IPsec (although, as a data point, QNX seems
to).
-
+
> Protocol stacks for control and data planes if using TLS.
@@ -1760,8 +1760,8 @@ protocol stack’.
The physical links available between the domains differ between
configurations of the domains, as do their properties. For some
-configurations ([][Standalone setup], [][Basic virtualised setup],
-[][Linux container setup])
+configurations ( [Standalone setup]( {{< ref "#standalone-setup" >}} ), [Basic virtualised setup]( {{< ref "#basic-virtualised-setup" >}} ),
+ [Linux container setup]( {{< ref "#linux-container-setup" >}} ))
confidentiality and integrity of the inter-domain communications
protocol are not strictly necessary, as the physical link itself cannot
be observed by an attacker. However, for the other configurations, these
@@ -1777,8 +1777,8 @@ the production code.
This should be weighed against the potential performance gains from
eliminating encryption from those connections, and the potential gains
-in debuggability (for the [][Standalone setup] and
-[][Linux container setup]) by being able to inspect
+in debuggability (for the [Standalone setup]( {{< ref "#standalone-setup" >}} ) and
+ [Linux container setup]( {{< ref "#linux-container-setup" >}} )) by being able to inspect
network traffic without needing to extract the encryption key.
**Open question**: What trade-off do we want between performance and
@@ -1793,7 +1793,7 @@ standalone setup is for development and is ignored by the security
model.
Even though there are only two peers communicating, they will both have
-and use a full addressing scheme ([][Addressing and peer discovery]).
+and use a full addressing scheme ( [Addressing and peer discovery]( {{< ref "#addressing-and-peer-discovery" >}} )).
###### Basic virtualised setup
@@ -1816,7 +1816,7 @@ virtualised configuration, as the security model guarantees that the
hypervisor maintains confidentiality and integrity of the connection.
Even though there are only two peers on the network, they will both have
-and use a full addressing scheme ([][Addressing and peer discovery]).
+and use a full addressing scheme ( [Addressing and peer discovery]( {{< ref "#addressing-and-peer-discovery" >}} )).
###### Separate CPUs setup
@@ -1915,7 +1915,7 @@ to be used as domain identifier for addressing and peer discovery purposes.
The `${IDC_DIR}` directory in the container contains a directory entry
for each associated domain to be connected through the inter-domain
-communication mechanism. As described in [][Linux container setup],
+communication mechanism. As described in [Linux container setup]( {{< ref "#linux-container-setup" >}} ),
the container manager is responsible for mounting a dedicated shared space
to host the socket for the container pairs.
@@ -1968,12 +1968,12 @@ certificate which is signed by a developer mode CA, not the production
mode CA. This allows a production mode domain to prevent connections
from a developer mode domain.
-See [][Appendix: Software versus hardware encryption] for a comparison of software and hardware encryption.
+See [Appendix: Software versus hardware encryption]( {{< ref "#appendix-software-versus-hardware-encryption" >}} ) for a comparison of software and hardware encryption.
In order to maintain confidentiality of the connection, the keys for the
IPsec connection must be kept confidential, which means they must be
stored in memory which is not accessible to an attacker who has physical
-access to the system (see [][Tamper evidence and hardware encryption]); or they must be encrypted under a
+access to the system (see [Tamper evidence and hardware encryption]( {{< ref "#tamper-evidence-and-hardware-encryption" >}} )); or they must be encrypted under a
key which is stored confidentially (a key-encrypting key, KEK). Such a
confidential key store should be provided by the Secure Boot
design — if available, confidentiality of the inter-domain
@@ -2055,7 +2055,7 @@ files on the CE. Finally, method calls support ‘in’ and ‘out’ parameters
(multiple return values) which allows for bi-directional communication
in the control protocol.
-**Open question**: How should the multiple CE configuration ([][Configuration designs]
+**Open question**: How should the multiple CE configuration ( [Configuration designs]( {{< ref "#configuration-designs" >}} )
interact with D-Bus signals? Can the adapter layer perform the
broadcast to all subscribers?
@@ -2078,8 +2078,8 @@ connection: TCP-like and UDP-like. These are implemented as TCP or UDP
connections between the two domains, running over IPsec. IPsec provides
the necessary authentication, confidentiality and integrity of the data;
TCP or UDP provide the multiplexing between connections (see the
-IPsec protocol stacks figure in [][IPSec versus TLS]).
-For [][Linux container setup] a Unix domain socket is used as the IDC link;
+IPsec protocol stacks figure in [IPSec versus TLS]( {{< ref "#ipsec-versus-tls" >}} )).
+For [Linux container setup]( {{< ref "#linux-container-setup" >}} ) a Unix domain socket is used as the IDC link;
the local kernel provides the needed authentication, confidentiality
and integrity of the data.
Services must implement their own application-specific protocols on top
@@ -2093,7 +2093,7 @@ they are the responsibility of the services themselves to design and
implement.
Data connections are opened by sending a request to one of the
-inter-domain services ([][Protocol library and inter-domain services]), specifying desired characteristics
+inter-domain services ( [Protocol library and inter-domain services]( {{< ref "#protocol-library-and-inter-domain-services" >}} )), specifying desired characteristics
for the connection, such as whether it should be TCP-like or UDP-like,
its bandwidth and latency requirements, etc. The connection will be
opened and a unique identifier and file descriptor for it returned to
@@ -2132,7 +2132,7 @@ data connection in reply.
Both inter-domain services should retain their file descriptors (which
they have shared with the OEM and SDK services) for the data connection,
-so that if the kill switch ([][Disabling the CE domain]) is enabled, they can call
+so that if the kill switch ( [Disabling the CE domain]( {{< ref "#disabling-the-ce-domain" >}} )) is enabled, they can call
shutdown() on the data connection to forcibly close it.
The inter-domain services must reserve all well-known names starting
@@ -2140,7 +2140,7 @@ with `org.apertis.InterDomain` (for example, `org.apertis.InterDomain1` or
`org.apertis.InterDomain1.DataConnections`), and similarly all D-Bus
interface names. This means they must not allow these names to be used
as part of the OEM API shared between the export and adapter layers
-([][Interaction of the export and adapter layers]).
+( [Interaction of the export and adapter layers]( {{< ref "#interaction-of-the-export-and-adapter-layers" >}} )).
A data connection cannot exist without an associated control connection
(though one control connection may be associated with many data
@@ -2193,7 +2193,7 @@ described above.
A fully decoded video stream consumes large quantities of bandwith and sharing
it between domains using the same approach used by audio (RTP) can only work
-for very small resolutions (see [][Memory bandwith usage on the i.MX6 Sabrelite]
+for very small resolutions (see [Memory bandwith usage on the i.MX6 Sabrelite]( {{< ref "#memory-bandwith-usage-on-the-imx6-sabrelite" >}} )
for the bandwidth limitations on one of the platforms targeted by Apertis).
If a domain sends uncompressed 1080p video stream at 25fps in YUV422 format to
@@ -2207,7 +2207,7 @@ toward the GPU where the decoded frames need to be composed.
To be able to handle 1080p video streams it is very important that zero-copy
mechanisms are used for the trasfer of frames, see
-[][Appendix: Audio and video decoding] for further considerations about how a
+ [Appendix: Audio and video decoding]( {{< ref "#appendix-audio-and-video-decoding" >}} ) for further considerations about how a
protocol can be defined to match such expectations.
#### Bulk data transfers
@@ -2505,7 +2505,7 @@ shares the file descriptor pointing to the file to the OTA updater with a
### Traffic control
-[Traffic control] should be set by the inter-domain service ([][Protocol library and inter-domain services])
+[Traffic control] should be set by the inter-domain service ( [Protocol library and inter-domain services]( {{< ref "#protocol-library-and-inter-domain-services" >}} ))
in the CE domain, using the standard Linux traffic control
functionality in the [kernel][linux-traffic-control]. As the control connection and each
data connection are separate TCP or UDP connections, they can have
@@ -2534,9 +2534,9 @@ to different types of traffic.
The inter-domain communications protocol should be implemented as a
library, containing all layers of the protocol. The particular domain
configuration which the library targets should be a configure-time
-option, though the library must support enabling the [][Standalone setup]
+option, though the library must support enabling the [Standalone setup]( {{< ref "#standalone-setup" >}} )
transport in conjunction with another transport, when in developer mode
-(see [][Mock SDK implementation]).
+(see [Mock SDK implementation]( {{< ref "#mock-sdk-implementation" >}} )).
By implementing the protocol as a library, it can be tested easily by
being linked into unit tests — rather than trying to wrap the entire
@@ -2552,7 +2552,7 @@ The main advantage of implementing the protocol as a library is the
flexibility this provides for integrating it into different automotive
domain implementations — it can be integrated into an existing system
service (bearing in mind the suggestion to keep it in a separate trust
-domain, [][Security domains]), or could be used as a stand-alone service daemon.
+domain, [Security domains]( {{< ref "#security-domains" >}} )), or could be used as a stand-alone service daemon.
A reference implementation of such a stand-alone inter-domain service
program should be provided with the protocol library. This should
@@ -2563,7 +2563,7 @@ this.
As the inter-domain communications protocol uses D-Bus, the protocol
library must contain an implementation of the D-Bus protocol. Note that
this is *not* a D-Bus daemon; it is a D-Bus library, like libdbus or
-GDBus. See [][Appendix: D-Bus components and licensing]
+GDBus. See [Appendix: D-Bus components and licensing]( {{< ref "#appendix-d-bus-components-and-licensing" >}} )
for details about the different components in
D-Bus and their licensing.
@@ -2579,7 +2579,7 @@ libdbus itself is already quite portable, having been known to work on
Linux, Windows, OS X, NetBSD and QNX. It should not be difficult to port
to other POSIX-compliant operating systems.
-[][Rate limiting on control messages] should be
+ [Rate limiting on control messages]( {{< ref "#rate-limiting-on-control-messages" >}} ) should be
implemented in the protocol library, so that the same functionality is
present in both the automotive and CE domains.
@@ -2587,7 +2587,7 @@ The protocol library should expose the encryption keys for the IPsec
connection used in the inter-domain communications link, including
signals for when those keys change (due to cookie renegotiation on the
link). The keys must only be exposed in development builds of the
-protocol library. See [][Debuggability] for more details.
+protocol library. See [Debuggability]( {{< ref "#debuggability" >}} ) for more details.
### Non Linux-based domains
@@ -2739,7 +2739,7 @@ the D-Bus connection. This effectively forms a whitelist of exposed
services.
For each piece of functionality exposed by the AD, suitable safety
-limits must be applied ([][Safety limits on AD APIs]). If the implementation of that
+limits must be applied ( [Safety limits on AD APIs]( {{< ref "#safety-limits-on-ad-apis" >}} )). If the implementation of that
functionality already applies the safety limits, nothing more needs to
be done. Otherwise, the safety limits must be enforced in the interface
code which exports that functionality onto the inter-domain D-Bus
@@ -2754,7 +2754,7 @@ ensure those calls cannot block the inter-domain service.
If the vendor wants to implement per-API kill switches for services
exported by the automotive domain, these must be implemented in the
-export layer (see [][Disabling the CE domain]).
+export layer (see [Disabling the CE domain]( {{< ref "#disabling-the-ce-domain" >}} )).
### Consumer-electronics domain adapter layer
@@ -2850,7 +2850,7 @@ calls from within the same process (no protocol at all), or D-Bus, or
kdbus, or QNX message passing, or something else
entirely.
-
+
> Apertis IDC message flow, following a message being sent from application
> to hardware; the message flow is the same in reverse for message replies
@@ -2913,7 +2913,7 @@ There are two implementation options:
layer.
The inter-domain services would be running in the same domain (the
SDK) and would communicate over a loopback TCP socket (see
- [][Standalone setup]).
+ [Standalone setup]( {{< ref "#standalone-setup" >}} )).
Option \#1 has a much simpler implementation, but option \#2 means that
the inter-domain communications code paths are tested by all application
@@ -2927,7 +2927,7 @@ As option \#2 uses the inter-domain service in the CE domain, it also
allows for the possibility of connecting the CE domain to a different
automotive domain — rather than the mock one provided by the SDK, a
developer could connect to the automotive domain in a development
-vehicle ([][Developer mode]).
+vehicle ( [Developer mode]( {{< ref "#developer-mode" >}} )).
Hence, our recommendation is for option \#2.
@@ -2938,7 +2938,7 @@ for many reasons, from integrating two domains to bringing up a new
automotive domain (with its export and adapter layers) to developing a
new SDK API.
-Referring to the figure in [][Overall architecture], debugging of:
+Referring to the figure in [Overall architecture]( {{< ref "#overall-architecture" >}} ), debugging of:
- *applications and the SDK services* happens using normal tools and
methods described in the [Debug and Logging design];
@@ -2969,7 +2969,7 @@ IPsec connection. This key may change over the lifetime of a
connection (as the connection cookie is refreshed), and hence needs to
be exported dynamically by the inter-domain service. In order to allow
debugging both ends of the connection, it should be implemented in the
-protocol library ([][Protocol library and inter-domain services]). In the CE domain, it should be exposed
+protocol library ( [Protocol library and inter-domain services]( {{< ref "#protocol-library-and-inter-domain-services" >}} )). In the CE domain, it should be exposed
as a D-Bus interface on the private bus which is part of the adapter
layer. This limits its access to developers who have access to that bus.
@@ -3058,7 +3058,7 @@ once that’s published.
A critical requirement of the system is that none of the keys for
encrypting inter-domain communications (or for protecting those keys)
can be shared between vehicles — they must be unique per vehicle
-([][No global keys in vehicles]). This implies that keys must be generated and
+( [No global keys in vehicles]( {{< ref "#no-global-keys-in-vehicles" >}} )). This implies that keys must be generated and
embedded into each vehicle as a stage in the imaging process for the
domains.
@@ -3068,7 +3068,7 @@ vehicles; as to do so would provide a single point of failure which, if
compromised by an attacker, could reveal the keys for all vehicles and
hence potentially allow them all to be compromised easily.
-Tamper evidence is an important requirement for the system ([][Tamper evidence]),
+Tamper evidence is an important requirement for the system ( [Tamper evidence]( {{< ref "#tamper-evidence" >}} )),
providing the ability to determine if a vehicle has been tampered
with in case of an accident or liability claim.
@@ -3184,31 +3184,31 @@ related back to the requirements to ensure they are all satisfied.
## Open questions
- - [][Existing inter-domain communication systems]: Are there any relevant existing systems to compare against?
+ - [Existing inter-domain communication systems]( {{< ref "#existing-inter-domain-communication-systems" >}} ): Are there any relevant existing systems to compare against?
- - [][IPSec versus TLS]: What is the security of the IPsec protocol in its current
+ - [IPSec versus TLS]( {{< ref "#ipsec-versus-tls" >}} ): What is the security of the IPsec protocol in its current
(2015) state?
- - [][IPSec versus TLS]: What is the performance of TCP and UDP over IPsec, TLS over
+ - [IPSec versus TLS]( {{< ref "#ipsec-versus-tls" >}} ): What is the performance of TCP and UDP over IPsec, TLS over
TCP and DTLS over UDP on the Apertis reference hardware?
- - [][Configuration designs]: What trade-off do we want between performance and testability
+ - [Configuration designs]( {{< ref "#configuration-designs" >}} ): What trade-off do we want between performance and testability
for the different transport layer configurations?
- - [][Configuration designs]: What more detailed configuration options can we specify for
+ - [Configuration designs]( {{< ref "#configuration-designs" >}} ): What more detailed configuration options can we specify for
setting up IPsec? For example, disabling various optional features
which are not needed, to reduce the attack surface. What IKE service
should be used?
- - [][Configuration designs]: A lot of business logic for control over OEM licencing can be
+ - [Configuration designs]( {{< ref "#configuration-designs" >}} ): A lot of business logic for control over OEM licencing can be
implemented by the choice of the CA hierarchy used by the
inter-domain communication system. What business logic should be
possible to implement?
- - [][Configuration designs]: Consider key control, revocation, protocol obsolescence, and
+ - [Configuration designs]( {{< ref "#configuration-designs" >}} ): Consider key control, revocation, protocol obsolescence, and
various extensions for pinning keys and protocols.
- - [][Configuration designs]: What can be done in the automotive domain to reduce the
+ - [Configuration designs]( {{< ref "#configuration-designs" >}} ): What can be done in the automotive domain to reduce the
possibility of exploits like Heartbleed affecting the inter-domain
communications link? This is a trade-off between the stability of AD
updates (high; rarely released) and the pace of IPsec and TLS
@@ -3216,30 +3216,30 @@ related back to the requirements to ensure they are all satisfied.
(fast). Heartbleed was a bug in a bad implementation of an optional
and not-very-useful TLS extension.
- - [][Control protocol]: How should the multiple CE configuration (section 8.3.2)
+ - [Control protocol]( {{< ref "#control-protocol" >}} ): How should the multiple CE configuration (section 8.3.2)
interact with D-Bus signals? Can the adapter layer perform the
broadcast to all subscribers?
- - [][Developer mode]: What cryptography should be used to implement this
+ - [Developer mode]( {{< ref "#developer-mode" >}} ): What cryptography should be used to implement this
authentication, and the division of trust between development and
production devices? A likely solution is to only have the AD accept
the CE connection if it connects with a ‘production’ key signed by
the vehicle OEM.
- - [][Disabling the CE domain]: What hardware provisions are available for controlling the
+ - [Disabling the CE domain]( {{< ref "#disabling-the-ce-domain" >}} ): What hardware provisions are available for controlling the
power supply or boot process of the CE domain? How should this
integrate with the secure boot design?
- - [][Suggested roadmap]: How does this design compare to the existing state of the
+ - [Suggested roadmap]( {{< ref "#suggested-roadmap" >}} ): How does this design compare to the existing state of the
inter-domain communication system?
- - [][Requirements]: Once the design is finalised a little more, it can be related
+ - [Requirements]( {{< ref "#requirements" >}} ): Once the design is finalised a little more, it can be related
back to the requirements to ensure they are all satisfied.
## Summary of recommendations
**Open question**: Once the design is finalised a little more, and a
-suggested roadmap has been produced ([][Suggested roadmap]), it can be summarised
+suggested roadmap has been produced ( [Suggested roadmap]( {{< ref "#suggested-roadmap" >}} )), it can be summarised
here.
## Appendix: D-Bus components and licensing
@@ -3635,7 +3635,7 @@ can be escalated to Code Execution as well.
This report indicates that demuxers might have a smaller attack surface than
decoders from the arbitrary code execution viewpoint. However, it is also
-possible to have a security hole similar to [][Video or audio decoder bugs].
+possible to have a security hole similar to [Video or audio decoder bugs]( {{< ref "#video-or-audio-decoder-bugs" >}} ).
Both demuxing and possibly even decoding in the CE can help to mitigate the
described attacks. If the CE is responsible of demuxing the AD does not
diff --git a/content/designs/internationalization.md b/content/designs/internationalization.md
index 72785d89e804d44259d777e4c9a779acbda815eb..cf96d96602ca97ffa95fc8ec576b2d4a98ea6783 100644
--- a/content/designs/internationalization.md
+++ b/content/designs/internationalization.md
@@ -198,12 +198,12 @@ the font size and the available space, plus having product variants that
share most of the code but can have differences in fonts and widget
sizes, we recommend to use mnemonics as IDs, which would allow us to
keep a list of the translatable strings and their associated fonts and
-pixels for each variant. This will be further discussed in [][Testing].
+pixels for each variant. This will be further discussed in [Testing]( {{< ref "#testing" >}} ).
This diagram illustrates the workflow that would be followed during
localization.
-
+
For better readability of the source code we recommend that the IDs
chosen suggest the meaning of the string, such as *PARK\_ASSIST\_1*.
@@ -274,7 +274,7 @@ Here is an example of an application running under a locale whose
orientation is right-to-left, note the alignment of icons in the toolbar
and the position of the arrows in submenus:
-
+
## Localization
@@ -294,7 +294,7 @@ latest code.
This diagram illustrates the [workflow][gnu-gettext-process] when using GNU gettext to
translate text in an application written in C:
-
+
From time to time, it is needed to extract new translatable strings from
the source code and update the files that are used by translators. The
@@ -344,7 +344,7 @@ Transifex is newer and was created to accommodate better than Pootle to
the actual workflows of most projects today. Its UI is richer in
features that facilitate translation and, more importantly, has good
commercial support (by [Indifex]). It provides as well an API that
-can be used to integrate it with other systems. See [][Transifex] for more
+can be used to integrate it with other systems. See [Transifex]( {{< ref "#transifex" >}} ) for more
details.
Launchpad is not easily deployable outside launchpad.net and is very
@@ -440,7 +440,7 @@ a [glossary][transifex-glossary] that will assist translators in these cases.
##### POT merging
-As explained in [][GNU Gettext], new translatable strings are extracted
+As explained in [GNU Gettext]( {{< ref "#gnu-gettext" >}} ), new translatable strings are extracted
from the source files with the tool xgettext and the resulting POT file
is merged into each PO file with the tool msgmerge.
@@ -494,7 +494,7 @@ to have available, during translation and along with the extracted
strings, the available space in pixels and the exact font description
used to display the string. This information would allow automatic
calculation of string sizes, thus being able to catch translations that
-would overflow the boundaries. As explained in [][Message IDs], this metadata
+would overflow the boundaries. As explained in [Message IDs]( {{< ref "#message-ids" >}} ), this metadata
would be stored in a file indexed by translation ID and would be merged
before importing it into the translation management software, which
could use it to warn when a translated string may be too long. For this
@@ -610,7 +610,7 @@ The Qt toolkit has a bit of support for this solution and their
easily implemented in Clutter and performance should be good provided
that there isn't an excessive amount of actors in the stage.
-
+
`LocaleManager` in the diagram would be a singleton that stores the
current locale and notifies interested parties when it changes. The
@@ -724,7 +724,7 @@ tools depending on their personal preferences.
This graph illustrates their work-flow:
-
+
[open-translation-tools]: http://en.flossmanuals.net/open-translation-tools/
diff --git a/content/designs/license-validation.md b/content/designs/license-validation.md
index 60dc09ea3264f52a8daaa2f21929a64ee04c4848..bd438d7fd3319be95adb7726f874601b63901ed7 100644
--- a/content/designs/license-validation.md
+++ b/content/designs/license-validation.md
@@ -258,7 +258,7 @@ to extract information when needed.
## Approach
The following proposal outlines the way FOSSology is meant to interact with other parts of system.
-
+
Inputs
* FOSSology server will be fed with source code tarballs from repositories, starting by adding packages which conform the target runtime into FOSSology bucket.
diff --git a/content/designs/list.md b/content/designs/list.md
index 3df1e64ca7bb0034c71b169d72e30eefce419a08..1cf76122fff9b1eb4fe3fb644fe5740c29747e19 100644
--- a/content/designs/list.md
+++ b/content/designs/list.md
@@ -19,7 +19,7 @@ different API and different usage. The goal is to consolidate list
operations into a base class and be able to use the same simple API to
use both cylindrical lists and non-cylindrical lists.
-
+
The above shows an example of the roller widget in use inside the music
application. There are multiple roller widgets for showing album,
@@ -141,7 +141,7 @@ unfocused visible item in the list simply by pressing it.
The user wants to have a smooth and natural experience in using either
list widget. If the scrolling stops half-way into an item and it is
-required that one item is focused (see [](#roller-focus-handling)), they want
+required that one item is focused (see[roller focus handling]( {{< ref "#roller-focus-handling" >}} )), they want
the list to bounce a small scroll to focus said item.
### Item launching
@@ -160,7 +160,7 @@ launching an item in a list. They want the two step process to be:
The application author wants to add a header to the column to make it
clear exactly what is in said column. (An example can be seen in
-[][List design] in the music application.)
+ [List design]( {{< ref "#list-design" >}} ) in the music application.)
Another system integrator wants the column names to be shown above the
widget in a footer instead of a header.
@@ -185,9 +185,8 @@ remaining space to be blank, but still used by the list widget.
### Click activation
A system integrator wants to choose between single click and double
-click activation (see [](#item-launching)) for use in the list widgets. This
-is only expected once the item has already been focused (see also
-[](#roller-focus-handling)).
+click activation (see[item launching]( {{< ref "#item-launching" >}} )) for use in the list widgets. This
+is only expected once the item has already been focused (see also[roller focus handling]( {{< ref "#roller-focus-handling" >}} )).
The decision of single or double click is given to the system integrator
instead of the application author in order to retain a consistent user
@@ -320,7 +319,7 @@ with the list widget.
### Common API
-There should be a common API between both list widgets (see [](#common-api)).
+There should be a common API between both list widgets (see[common api]( {{< ref "#common-api" >}} )).
Changing from a list widget to a roller widget or the other way around
should involve only trivial changes to the code leading to a change in
behaviour.
@@ -329,7 +328,7 @@ behaviour.
The separation between components that use the list widgets should be
functional and enable application authors and system integrators to swap
-out parts of applications easily and quickly (see [](#mvc-separation)).
+out parts of applications easily and quickly (see[mvc separation]( {{< ref "#mvc-separation" >}} )).
The implementation of the model should be of no impact to the
functionality of the widget. As a result the widget should only refer to
@@ -342,8 +341,7 @@ model in any particular way.
### Kinetic scrolling
-Both list widgets should support kinetic scrolling from user inputs (see
-[](#kinetic-scrolling)). That is, when the user scrolls using their finger,
+Both list widgets should support kinetic scrolling from user inputs (see[kinetic scrolling]( {{< ref "#kinetic-scrolling" >}} )). That is, when the user scrolls using their finger,
he or she can *flick* the list up or down and the scroll will continue
after the finger is released and gradually slow down. This animation
should feel natural to the user as if he or she is moving a wheel up or
@@ -363,7 +361,7 @@ This is not necessary on the roller widget because the list loops and
there is no defined start and finish to the list.
It should be easy to turn this feature off as it may be undesired by the
-system integrator (see [](#kinetic-scrolling)).
+system integrator (see[kinetic scrolling]( {{< ref "#kinetic-scrolling" >}} )).
### Item focus
@@ -374,9 +372,9 @@ depends on the widget.
### Roller focus handling
In the roller widget the focused item should always be in the vertical
-centre of the widget (see [](#roller-focus-handling)). The focused item
+centre of the widget (see[roller focus handling]( {{< ref "#roller-focus-handling" >}} )). The focused item
should visually change and even expand if necessary to demonstrate its
-focused state (see also [](#focus-animation)).
+focused state (see also[focus animation]( {{< ref "#focus-animation" >}} )).
Changing which item is focused should be possible by clicking on another
item in the list.
@@ -384,31 +382,30 @@ item in the list.
### Animations
It should be possible to add animations to widgets to allow for moving
-the current scroll location of the list up or down (see [](#animations)).
+the current scroll location of the list up or down (see[animations]( {{< ref "#animations" >}} )).
This should be customisable by the system integrator and application
author depending on the application in question but should retain the
general look and feel across the entire system.
### Item launching
-Focused items (see [][Item focus]) should be able to be launched using
-widget-specific bindings (clicks or touches) (see [][Click activation]).
+Focused items (see [Item focus]( {{< ref "#item-focus" >}} )) should be able to be launched using
+widget-specific bindings (clicks or touches) (see [Click activation]( {{< ref "#click-activation" >}} )).
### Header and footer
It should be possible to add a header to a list to provide more context
-as to what the information is showing (see [](#header-and-footer) and the
-screenshot in [][List design]). This should be customisable by the
+as to what the information is showing (see[header and footer]( {{< ref "#header-and-footer" >}} ) and the
+screenshot in [List design]( {{< ref "#list-design" >}} )). This should be customisable by the
application author and should be consistent across the entire system.
### Roller rollover
The rollover of the two list widgets should be different and
-customisable by the system integrator (see [](#roller-rollover) and
-[](#ui-customisation)).
+customisable by the system integrator (see[roller rollover]( {{< ref "#roller-rollover" >}} ) and[ui customisation]( {{< ref "#ui-customisation" >}} )).
The roller widget should roll over from the end of the list back to the
-beginning again, like a cylinder would (see [][List design] and [][Roller]).
+beginning again, like a cylinder would (see [List design]( {{< ref "#list-design" >}} ) and [Roller]( {{< ref "#roller" >}} )).
Additionally the system integrator should be able to customise whether
they want extra resistance in going back to the beginning. This is
visual feedback to ensure the user knows they are returning to the
@@ -416,27 +413,26 @@ beginning of the list.
The non-roller list widget should not have a rollover and should have a
well-defined start and finish, with visual effects as appropriate (see
-[][Elastic effect]).
+ [Elastic effect]( {{< ref "#elastic-effect" >}} )).
### Widget size
The list widgets should expand to fill out all space that has been
-provided to them (see [](#widget-size)). They should fill any space not
+provided to them (see[widget size]( {{< ref "#widget-size" >}} )). They should fill any space not
required with a blank colour, specified by the variant UI customisation
-(see [](#ui-customisation)).
+(see[ui customisation]( {{< ref "#ui-customisation" >}} )).
### Consistent focus
The focus of items in a list should remain consistent despite
-modification of the list contents (see [](#consistent-focus)). Adding items
+modification of the list contents (see[consistent focus]( {{< ref "#consistent-focus" >}} )). Adding items
before or after the currently focused item shouldn't change its focused
state.
### Focus animation
The application author and system integrator should be able to specify
-whether there is an animation in selecting an item in a list (see
-[](#focus-animation) and [](#ui-customisation)). This could mean expanding an item to
+whether there is an animation in selecting an item in a list (see[focus animation]( {{< ref "#focus-animation" >}} ) and[ui customisation]( {{< ref "#ui-customisation" >}} )). This could mean expanding an item to
make the item focused larger vertically and even display extra controls
which were previously hidden under the fold.
@@ -445,33 +441,32 @@ During this animation, input should not be possible.
### Mutable list
The items shown in the list widgets and their content should update
-dynamically when the model backing the widget is updated (see
-[](#mutable-list)). This should require no extra effort on the part of the
+dynamically when the model backing the widget is updated (see[mutable list]( {{< ref "#mutable-list" >}} )). This should require no extra effort on the part of the
application author.
### UI customisation
Both list widgets should be visibly customisable in the same way the
rest of the system is and should honour UI customisations made by the
-system integrator (see [](#ui-customisation)). In this way, the list widgets
+system integrator (see[ui customisation]( {{< ref "#ui-customisation" >}} )). In this way, the list widgets
should use CSS (see the UI Customisation Design document) for styling.
### Blur effect
The list widget should support slightly blurring list items only when
-scrolling (see [](#blur-effect)). It should be easily to disable this feature
+scrolling (see[blur effect]( {{< ref "#blur-effect" >}} )). It should be easily to disable this feature
by another system integrator who doesn't want the blur.
### Scrollbar
The list widget should support showing and hiding a scrollbar as
-necessary (see [](#scrollbar)). It should be easy to disable this feature by
+necessary (see[scrollbar]( {{< ref "#scrollbar" >}} )). It should be easy to disable this feature by
another system integrator who doesn't want to display a scrollbar.
### Hardware scroll
The list widget should support scrolling using hardware buttons and
-therefore always have one item focused ([](#hardware-scroll)). Hardware
+therefore always have one item focused [hardware scroll]( {{< ref "#hardware-scroll" >}} )). Hardware
button callbacks should use the [adjustments][mx-scrollable] on the list widget to
change the subset of visible items and the appropriate list widget
function for moving the focus to the next item. Hardware button signals
@@ -481,18 +476,18 @@ are generated as described in the Hardkeys Design.
Items in the list need to know when they are visible (and not past the
current scroll area) so they know when to load expensive resources, such
-as thumbnails from disk (see [][On-demand item resource loading]).
+as thumbnails from disk (see [On-demand item resource loading]( {{< ref "#on-demand-item-resource-loading" >}} )).
### Scroll bubbles
-The scrollbar (see also [](#scrollbar)) should support showing bubbles to
-show the scroll position (see [](#scroll-bubbles)). It should be possible to
+The scrollbar (see also[scrollbar]( {{< ref "#scrollbar" >}} )) should support showing bubbles to
+show the scroll position (see[scroll bubbles]( {{< ref "#scroll-bubbles" >}} )). It should be possible to
disable the bubble and change its appearance when necessary.
### Item headers
It should be possible to add separating headers to sets of items in the
-list widgets (see [](#item-headers)). Said headers should also be sticky if
+list widgets (see[item headers]( {{< ref "#item-headers" >}} )). Said headers should also be sticky if
specified.
### Lazy list model
@@ -504,7 +499,7 @@ displayed to the user.
This model could make memory usage and instantiation performance independent
of the number of items in the model.
-See [][List with tens of thousands of items]
+See [List with tens of thousands of items]( {{< ref "#list-with-tens-of-thousands-of-items" >}} )
### Flow layout
@@ -518,13 +513,13 @@ to set *n* manually.
The underlying model should not have to be duplicated in order to present it
in multiple list widgets at the same time.
-See [][Concurrent presentation of the same model in different list widgets]
+See [Concurrent presentation of the same model in different list widgets]( {{< ref "#concurrent-presentation-of-the-same-model-in-different-list-widgets" >}} )
## Approach
### Adapter interface
-As required by [](#data-backend-agnosticity1), the backing data model format
+As required by[data backend agnosticity1]( {{< ref "#data-backend-agnosticity1" >}} ), the backing data model format
should not be imposed by the list widget upon the application developer.
As such, an ‘adapter’ is required, similar to Android's [`ListAdapter`], this
@@ -541,7 +536,7 @@ widget from the underlying model.
> exposing items stored in a database, and an adapter that stores strong
> references to the created list items, and will eventually cache them all
> if the list widget is fully scrolled down by the user. This is as opposed to
-> the approach presented in [][Lazy list model] where memory usage is also
+> the approach presented in [Lazy list model]( {{< ref "#lazy-list-model" >}} ) where memory usage is also
> taken into account.
>
> The ‘cursor’ is a representation of whatever database access API is in use,
@@ -549,12 +544,12 @@ widget from the underlying model.
An interface for this adapter (the contents of the list widgets) is
required such that it can be swapped out easily where necessary
-(see [](#mvc-separation), [][Lazy list model]).
+(see[mvc separation]( {{< ref "#mvc-separation" >}} ), [Lazy list model]( {{< ref "#lazy-list-model" >}} )).
GLib recently (since version 2.44) added an interface for this very
task. [`GListModel`] is an implementation-agnostic interface for
representing lists in a single dimension. It does not support tree
-models (see [][Tree views]) and contains everything required for the
+models (see [Tree views]( {{< ref "#tree-views" >}} )) and contains everything required for the
requirements specified in this document.
It should be noted that `GListModel`, which is for arbitrary containers, is
@@ -563,7 +558,7 @@ lists.
In addition to functions for accessing the contents of the adapter, there is
also an `items-changed` signal for notifying the view (the list widget and list
-item widgets it contains; see [](#mvc-separation))
+item widgets it contains; see[mvc separation]( {{< ref "#mvc-separation" >}} ))
that it should re-render as a result of something changing in the adapter.
### GtkListBox
@@ -576,8 +571,7 @@ often lists are used instead of trees.
`GtkListBox` doesn't have a separate model backing it (but one can be
used), and each item is a `GtkListBoxRow` (which is in turn a `GtkWidget`).
This makes using the widget and modifying its contents especially easy
-using the [`GtkContainer`] functions. Items can be activated (see
-[](#item-launching) or selected (see [][Item focus]).
+using the [`GtkContainer`] functions. Items can be activated (see[item launching]( {{< ref "#item-launching" >}} ) or selected (see [Item focus]( {{< ref "#item-focus" >}} )).
`GtkListBox` has been used in many GNOME applications since its addition
and has shown that its API is sufficient for most simple use cases, with
@@ -589,7 +583,7 @@ to sections, and still be able to scroll accurately to any random position
in the list (random access).
As such, its API is only of a limited interest to us, particularly when it
-comes to [](#item-headers) or [](#filtering).
+comes to[item headers]( {{< ref "#item-headers" >}} ) or[filtering]( {{< ref "#filtering" >}} ).
### GtkFlowBox
@@ -599,12 +593,11 @@ separate model backing it – but one can be used – and each item is a
`GtkFlowBoxChild` which contains the content for that item.
As with `GtkListBox`, its API is interesting to us for its approach to
-reflowing children; see [][Column layout].
+reflowing children; see [Column layout]( {{< ref "#column-layout" >}} ).
### Widget size
-The list widgets should expand to fill space assigned to them (see
-[](#widget-size)). This means that when there are too few items to fill space
+The list widgets should expand to fill space assigned to them (see[widget size]( {{< ref "#widget-size" >}} )). This means that when there are too few items to fill space
the remaining space should be filled appropriately, but when there are
more items than can be shown at one time the list should be put into a
scrolling container.
@@ -634,15 +627,15 @@ clutter_actor_set_x_align (fourth_actor, CLUTTER_ACTOR_ALIGN_CENTER);
More details can be found in the [`ClutterActor`] documentation.
-The list item widgets (as described in [](#adaptermodel-implementation)) are packed
+The list item widgets (as described in[adaptermodel implementation]( {{< ref "#adaptermodel-implementation" >}} )) are packed
by the list widget and so application authors have no control over their
expanding or alignment.
A suitable scrolling container to put a list widget into is the
-[`MxKineticScrollView`] as it provides kinetic scrolling (see [](#kinetic-scrolling)
-and [][Elastic effect]) using touch events. Additionally, the
+[`MxKineticScrollView`] as it provides kinetic scrolling (see[kinetic scrolling]( {{< ref "#kinetic-scrolling" >}} )
+and [Elastic effect]( {{< ref "#elastic-effect" >}} )) using touch events. Additionally, the
`MxKineticScrollView` should be put into an `MxScrollView` to get a
-scrollbar where appropriate (see [](#scrollbar)).
+scrollbar where appropriate (see[scrollbar]( {{< ref "#scrollbar" >}} )).
For support of `MxKineticScrollView` the list widgets should implement the
`MxScrollable` interface, which allows getting and setting the
@@ -654,7 +647,7 @@ a system integrator are much more difficult to achieve.
### Adapter/Model implementation
-As highlighted before (in [][Adapter interface]), the list widget should
+As highlighted before (in [Adapter interface]( {{< ref "#adapter-interface" >}} )), the list widget should
make no assumption about how the backing data is stored. An adapter data
structure should be provided, making the bridge between the backing data
and the list widget, by returning list item actors for any given position.
@@ -676,17 +669,17 @@ In these simple cases, `GListStore` will act as both the adapter *and* the
backing model, as it is storing `ListItem` widgets. For more complicated use
cases (where the same data source is being used by multiple list widgets), the
adapter and backing model must be separated, and hence `GListStore` is not
-appropriate as the adapter in those cases. See [][Decoupled model].
+appropriate as the adapter in those cases. See [Decoupled model]( {{< ref "#decoupled-model" >}} ).
### Decoupled model
-As shown in [][Adapter interface], the list widget will not directly
+As shown in [Adapter interface]( {{< ref "#adapter-interface" >}} ), the list widget will not directly
interact with the underlying data model, but through an ‘adapter’.
The following diagram shows how the same underlying model may be queried
by two different list widgets, and their corresponding adapters.
-
+
> List widgets are the outermost boxes in the diagram; the adapters are the
> next boxes inwards; and the middle box is the shared data model (a database).
@@ -706,7 +699,7 @@ every single item in the list at initialisation.
will need to be implemented by applications which need to deal with
huge models.
-An example for this is provided in [][Alternative list adapter].
+An example for this is provided in [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ).
### High-level helpers
@@ -745,10 +738,10 @@ subclasses to provide their own list item widgets for properties that may or
may not be handled by the default implementation, and to provide their own list
item widgets for each of the GObjects in the model. These are represented by
`create_view_for_property()` and `create_view_for_object()` on the
-[][API diagram].
+ [API diagram]( {{< ref "#api-diagram" >}} ).
The adapter should use weak references on the created list items, as
-examplified in [][Alternative list adapter].
+examplified in [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ).
Filtering and sorting should be implemented by this adapter, with the option
for the user to provide implementations of the sorting and filtering methods,
@@ -760,8 +753,8 @@ If developers want to use the list widget with an underlying model that
allows more efficient sorting and filtering (for example a database), they
should implement their own adapter.
-Refer to the [][API diagram] for a more formal view of the proposed API,
-and to the [][Generic adapter] section for a practical usage example.
+Refer to the [API diagram]( {{< ref "#api-diagram" >}} ) for a more formal view of the proposed API,
+and to the [Generic adapter]( {{< ref "#generic-adapter" >}} ) section for a practical usage example.
### UI customisation
@@ -785,7 +778,7 @@ argument pointing to a function to help sort the model. All items can be
sorted at once using the `g_list_store_sort` function, passing in the
same or different sorting function.
-When using an [][Alternative list adapter], sorting will need to be
+When using an [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ), sorting will need to be
implemented on a case-by-case basis.
### Filtering
@@ -820,16 +813,16 @@ application may use different widgets in each.
### Selections
As with `GtkListBox`, it should be possible to select either one or many
-items in the list (see [][Item focus]). The application author can decide
+items in the list (see [Item focus]( {{< ref "#item-focus" >}} )). The application author can decide
what is the behaviour of the list in question using the “selection
modeâ€. The values for the selection mode are none (no items can be
selected), single (at most one item can be selected), and multiple (any
number of items can be selected). A multiple selection example can be found
-in the [][Multiple selection] section.
+in the [Multiple selection]( {{< ref "#multiple-selection" >}} ) section.
The `ListItem` object has a read-write property for determining it can be
selected or not. An example that sets this property can be found
-in the [][Non-selectable items] section.
+in the [Non-selectable items]( {{< ref "#non-selectable-items" >}} ) section.
The selection signals exposed by the list widget will be identical to those
exposed by `GtkListBox`, namely `item-selected` when an item is focused,
@@ -870,7 +863,7 @@ An example of item headers is shown in [the following section][Header items].
### Sticky item headers
-As required for [][Lazy list model], when the list widget is scrolled to
+As required for [Lazy list model]( {{< ref "#lazy-list-model" >}} ), when the list widget is scrolled to
a random point, items surrounding the viewport may not be created yet.
It is proposed that a simple API be exposed to let application developers
@@ -884,7 +877,7 @@ that should be stickied (or `NULL`).
### Blur effect
Given the `MxKineticScrollView` container does the actual scrolling, it is
-the best place to implement the desired blur effect (see [](#blur-effect)).
+the best place to implement the desired blur effect (see[blur effect]( {{< ref "#blur-effect" >}} )).
Additionally, implementing it in the container means it can be
implemented once instead of in every widget that needs to have a blur
effect.
@@ -893,7 +886,7 @@ effect.
By default, list items should assume they are not in view and should not
perform expensive operations until they have been signalled by the list
-widget that they are in view (see [][On-demand item resource loading]). For
+widget that they are in view (see [On-demand item resource loading]( {{< ref "#on-demand-item-resource-loading" >}} )). For
example, a music application might have a long list of albums and each
item has the album cover showing. Instead of loading every single album
cover when creating the list, each list item should use a default dummy
@@ -911,7 +904,7 @@ visible state.
### Scroll bubbles
The bubble displayed when scrolling to indicate in which category the
-scroll is showing (see [](#scroll-bubbles)) should be added to `MxScrollBar` as
+scroll is showing (see[scroll bubbles]( {{< ref "#scroll-bubbles" >}} )) should be added to `MxScrollBar` as
that is the widget that controls changing the scroll position.
### Roller subclass
@@ -959,7 +952,7 @@ an item with this property set to `True` will be animated to cover the whole
width and height allocated to the list widget.
Application developers may connect to the `item-activated` signal in order to
-update the contents of the item, as shown in [][Item activation].
+update the contents of the item, as shown in [Item activation]( {{< ref "#item-activation" >}} ).
Once the set of possible and valuable animations has become clearer, API
may be exposed to give more control to system integrators and application
@@ -973,7 +966,7 @@ that were scrolled to can be activated.
### API diagram
-
+
Signals are shown with a hash beforehand (for example, `#item-activated`),
with arguments listed afterwards. Properties are shown with a plus sign
@@ -1015,7 +1008,7 @@ change the list item actor.
### Filtering
The following example shows how to filter the list store bound to the list
-widget created using the function implemented in [][Basic usage]
+widget created using the function implemented in [Basic usage]( {{< ref "#basic-usage" >}} )
to only display items with a specific property.
{{ ../examples/sample-list-api-usage-filtering.c }}
@@ -1070,75 +1063,75 @@ items.
This design fulfils the following requirements:
- - [](#common-api1) — the list widget and roller widget have the same
+ -[common api1]( {{< ref "#common-api1" >}} ) — the list widget and roller widget have the same
API and any roller-specific roller API is in its own class.
- - [](#mvc-separation1) — `GListModel` is used as an adapter to the backing
+ -[mvc separation1]( {{< ref "#mvc-separation1" >}} ) — `GListModel` is used as an adapter to the backing
data, which storage format is not imposed to the user. The list widget
and item widgets are separate objects.
- - [](#data-backend-agnosticity1) — Applications provide list items through
+ -[data backend agnosticity1]( {{< ref "#data-backend-agnosticity1" >}} ) — Applications provide list items through
an adapter, no requirement is made as to the storage format.
- - [](#kinetic-scrolling1) — use `MxKineticScrollView`.
+ -[kinetic scrolling1]( {{< ref "#kinetic-scrolling1" >}} ) — use `MxKineticScrollView`.
- - [][Elastic effect] — use `MxKineticScrollView`.
+ - [Elastic effect]( {{< ref "#elastic-effect" >}} ) — use `MxKineticScrollView`.
- - [][Item focus] — list items can be selected ([][Selections]).
+ - [Item focus]( {{< ref "#item-focus" >}} ) — list items can be selected ( [Selections]( {{< ref "#selections" >}} )).
- - [](#roller-focus-handling1) — this roller-specific selecting
+ -[roller focus handling1]( {{< ref "#roller-focus-handling1" >}} ) — this roller-specific selecting
behaviour can be added to the roller's class.
- - [](#animations1) — use `MxKineticScrollView`.
+ -[animations1]( {{< ref "#animations1" >}} ) — use `MxKineticScrollView`.
- - [](#item-launching1) — the item-activated signal on the list widget
+ -[item launching1]( {{< ref "#item-launching1" >}} ) — the item-activated signal on the list widget
will signal when an item is activated.
- - [](#header-and-footer1) — `ApertisWidget`s can be set as header or footer
- ([](#header-and-footer2)).
+ -[header and footer1]( {{< ref "#header-and-footer1" >}} ) — `ApertisWidget`s can be set as header or footer
+ [header and footer2]( {{< ref "#header-and-footer2" >}} )).
- - [](#roller-rollover1) — this roller-specific rollover behaviour can
+ -[roller rollover1]( {{< ref "#roller-rollover1" >}} ) — this roller-specific rollover behaviour can
be added to the roller's class.
- - [](#widget-size1) — use `ClutterLayoutManager` and the `ClutterActor`
- properties ([](#widget-size2)).
+ -[widget size1]( {{< ref "#widget-size1" >}} ) — use `ClutterLayoutManager` and the `ClutterActor`
+ properties [widget size2]( {{< ref "#widget-size2" >}} )).
- - [](#consistent-focus1) — the API asserts a consistent focus and
+ -[consistent focus1]( {{< ref "#consistent-focus1" >}} ) — the API asserts a consistent focus and
ensures the implementation behaves when the model changes.
- - [](#focus-animation1) — items are `ClutterActor`s which can animate
+ -[focus animation1]( {{< ref "#focus-animation1" >}} ) — items are `ClutterActor`s which can animate
using regular Clutter API.
- - [](#mutable-list1) — use `GListStore`.
+ -[mutable list1]( {{< ref "#mutable-list1" >}} ) — use `GListStore`.
- - [](#ui-customisation1) — subclass `ApertisWidget` and use the
+ -[ui customisation1]( {{< ref "#ui-customisation1" >}} ) — subclass `ApertisWidget` and use the
`GtkStyleProvider`s.
- - [](#blur-effect1) — add a `motion-blur` property to
- `MxKineticScrollView` and use that ([](#blur-effect2)).
+ -[blur effect1]( {{< ref "#blur-effect1" >}} ) — add a `motion-blur` property to
+ `MxKineticScrollView` and use that [blur effect2]( {{< ref "#blur-effect2" >}} )).
- - [](#scrollbar1) — use the `scroll-visibility` property on the
+ -[scrollbar1]( {{< ref "#scrollbar1" >}} ) — use the `scroll-visibility` property on the
`MxScrollView` container.
- - [](#hardware-scroll1) — use the adjustment on the list widget to
+ -[hardware scroll1]( {{< ref "#hardware-scroll1" >}} ) — use the adjustment on the list widget to
scroll down a page, and use the appropriate function to move the
selection on.
- - [][On-demand item resource loading1] — ensure list widget can look
+ - [On-demand item resource loading1]( {{< ref "#on-demand-item-resource-loading1" >}} ) — ensure list widget can look
up the item based on co-ordinates, and add a property to the list
item object to denote whether it’s in view, which the list widget
updates.
- - [](#scroll-bubbles1) — add support for overlay actors to
+ -[scroll bubbles1]( {{< ref "#scroll-bubbles1" >}} ) — add support for overlay actors to
`MxScrollBar`.
- - [](#item-headers1) — Added as regular `ListItem`s in the adapter, a
+ -[item headers1]( {{< ref "#item-headers1" >}} ) — Added as regular `ListItem`s in the adapter, a
`list_set_sticky_func` API is exposed.
- - [][Lazy list model] — see [][Alternative list adapter], for an example
+ - [Lazy list model]( {{< ref "#lazy-list-model" >}} ) — see [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ), for an example
of how application developers may implement their own model.
- - [][Flow layout] — The number of columns is calculated by dividing the
+ - [Flow layout]( {{< ref "#flow-layout" >}} ) — The number of columns is calculated by dividing the
list width by the specified item width. Padding between the resulting
columns and rows may be specified using `row-spacing` and `column-spacing`
properties.
@@ -1173,9 +1166,9 @@ As discussed in the above sections, we recommend:
### Existing roller design
-
+
-
+
[bubbles]: http://i.stack.imgur.com/YyRtC.png
diff --git a/content/designs/long-term-reproducibility.md b/content/designs/long-term-reproducibility.md
index 95695619c7d08d6af4dd283fb9741bb51b5e5ae9..b6a8b20ff88a811e42768e57e9662b22f279f1c4 100644
--- a/content/designs/long-term-reproducibility.md
+++ b/content/designs/long-term-reproducibility.md
@@ -39,7 +39,7 @@ while the runtime behavior is not affected.
# Apertis artifacts and release channels
-As described in the [](release-flow.md) document, at any given time Apertis
+As described in the[release flow]( {{< ref "release-flow.md" >}} ) document, at any given time Apertis
has multiple active release channels to both provide a stable foundation for
product teams and also give them full visibility on the latest developments.
@@ -77,13 +77,13 @@ an identifier for each of them to uniquely identify them. For instance,
the pipeline saves all the git commit hashes, Docker image hashes, and
package versions in the output metadata.
-
+
While the pipeline defaults to using the latest version available in a specific
channel for each input, it is possible to pin specific version to closely
reproduce a past build using the identifiers saved in its metadata.
-
+
## Reproducible build environments
@@ -165,7 +165,7 @@ GitLab that OBS uses to generate pre-built binaries to be published in a
APT-compatible repository.
Separate git branches and OBS projects are used to track packages and versions
-across different parallel releases, see the [](release-flow.md) document for
+across different parallel releases, see the[release flow]( {{< ref "release-flow.md" >}} ) document for
more details.
For instance, for the v2020 stable release:
@@ -273,7 +273,7 @@ matching git tag.
Other files capture other pieces of information that can be useful to reproduce
builds. For instance the `build-url` point to the full log of the build where
the recipe commit hash and the Docker image hash can be identified, however in
-the [](#implementation-plan) section a few improvements are described to make
+the[implementation plan]( {{< ref "#implementation-plan" >}} ) section a few improvements are described to make
that information easier to retrieve and use.
## Package builds
diff --git a/content/designs/media-management.md b/content/designs/media-management.md
index d3e057bb8426b396ee65576c8fb1814d186d357d..0dfe5acdd8fc3acac50feb7b31bddad0b0b51ea5 100644
--- a/content/designs/media-management.md
+++ b/content/designs/media-management.md
@@ -21,8 +21,8 @@ following operations with media:
- **Media Browsing**: locate the media content and access its
metadata.
-[][Solution] provides a general overview of the technologies used,
-like an executive summary of [][Appendix: Media management technologies], as well as a high level view of
+ [Solution]( {{< ref "#solution" >}} ) provides a general overview of the technologies used,
+like an executive summary of [Appendix: Media management technologies]( {{< ref "#appendix-media-management-technologies" >}} ), as well as a high level view of
the solution proposed. Additionally, it exposes in detail the media
management requirements in the Apertis platform, providing an analysis
as well as a solution to each requirement, which might involve modifying
@@ -34,12 +34,12 @@ like global search, which allows to search not only in media content but
also in applications, messages, calendar events, etc. For details on
global search please check its specific design.
-[][Appendix: Media management technologies] is mostly used as
+ [Appendix: Media management technologies]( {{< ref "#appendix-media-management-technologies" >}} ) is mostly used as
reference material from other sections of the document, so it is not
necessary to read from start-to-finish. It has a detailed description of
the current state of the technologies used for media management without
including specific requirements, additions and modifications described
-on [][Solution].
+on [Solution]( {{< ref "#solution" >}} ).
This document assumes the adoption of a media-centric approach for
applications (every media source provider will have its own application
@@ -82,7 +82,7 @@ used in the design:
Store. Tracker Miner automatically crawls for media content files.
Tracker Extract gathers useful metadata from these files and it
stores this metadata in the Tracker Store database. Metadata can be
- retrieved from the Tracker Store with SPARQL queries. See [][Tracker]
+ retrieved from the Tracker Store with SPARQL queries. See [Tracker]( {{< ref "#tracker" >}} )
for more details. Although this document will only focus
on the Tracker features specific to media indexing, Tracker can be
used to store other information as well, like applications,
@@ -92,15 +92,15 @@ used in the design:
- **Grilo** is a simple API for browsing media content and provide
media content metadata. Grilo layer helps to hide the complexities
of Tracker and its query language, by focusing on media content
- (since Tracker is much more generic). See [][Grilo] for more
+ (since Tracker is much more generic). See [Grilo]( {{< ref "#grilo" >}} ) for more
details.
- **Tumbler**. It is a service for accessing and caching thumbnails.
- See [][Thumbnail management] for more details.
+ See [Thumbnail management]( {{< ref "#thumbnail-management" >}} ) for more details.
- **libsoup** and **librest** are libraries simplifying the creation
of HTTP client/servers and the access to REST-based services
- respectively. See [][Librest and Libsoup].
+ respectively. See [Librest and Libsoup]( {{< ref "#librest-and-libsoup" >}} ).
- **libgdata** is a library implementing the Google Data Protocol. It
provides access to Google Services like YouTube and Picasa, among
@@ -142,7 +142,7 @@ See this illustration for an overview of the general architecture. Some of
the components listed will be introduced with more detail in the
following chapters.
-
+
### **Local Storage Media Source**
@@ -154,7 +154,7 @@ metadata is required.
**Solution**. Collabora proposes a combination of Tracker and Grilo, as
a powerful solution for this endeavor (see section 2.1). Tracker can be
-reviewed in detail in [][Technology and solution overview], and [][Grilo] in chapter 3.3. Upper
+reviewed in detail in [Technology and solution overview]( {{< ref "#technology-and-solution-overview" >}} ), and [Grilo]( {{< ref "#grilo" >}} ) in chapter 3.3. Upper
layers will just interact with the Grilo layer, which is a simple API
specialized in media browsing hiding the complexity of Tracker.
@@ -204,7 +204,7 @@ work. To minimize this delay, Tracker scheduler will be changed to get
filesystem information before other media metadata. Obtaining the
filesystem information is very fast compared to the extraction of the
metadata (which involves reading the file contents). Some timings have
-been gathered to show this fact, check the table in [][Appendix: Questions [Appendix: Questions (#appendix-questions--answers) Answers] Answers] for the
+been gathered to show this fact, check the table in [Appendix: Questions [Appendix: Questions (#appendix-questions--answers) Answers]( {{< ref "#appendix-questions-[appendix-questions-#appendix-questions--answers-answers" >}} ) Answers] for the
details. This solution plays nicely with requirement R3 (to get
notifications of ready metadata as soon as it is available) and with R8
and R13 (regarding the scheduling of operations like crawling, metadata
@@ -220,7 +220,7 @@ Grilo Tracker plugin will need to be modified to operate as specified in
the solution, and it actually depends on requirement R8 and R13 related
to Tracker scheduling. Additionally, an API would need to be provided to
change easily from one hierarchical model to the other on run-time. See
-[][Grilo Media Source Plugins] for more information about
+ [Grilo Media Source Plugins]( {{< ref "#grilo-media-source-plugins" >}} ) for more information about
Grilo.
**Status**. Satisfied.
@@ -250,14 +250,14 @@ extract the information again.
**Solution**: Grilo tracks changes in Tracker Store by subscribing to
the **GraphUpdated** D-Bus signal from the Tracker Store service (see
-[][Tracker storage] for more details). Grilo processes this
+ [Tracker storage]( {{< ref "#tracker-storage" >}} ) for more details). Grilo processes this
information and provides notifications of changes on media content. See
the following illustration for an overview of the interaction between the components
involved.
**Status**. Satisfied.
-
+
#### **Paged queries**
@@ -271,7 +271,7 @@ incrementally as needed is required.
**Solution**: Grilo supports paging in all requests via skip and count
numbers. Internally Grilo uses both mechanisms provided by Tracker
SPARQL (OFFSET / LIMIT modifiers in the SELECT SPARQL statements and
-TrackerSparqlCursor). See [][Grilo] for details on Grilo.
+TrackerSparqlCursor). See [Grilo]( {{< ref "#grilo" >}} ) for details on Grilo.
**Status**. Satisfied.
@@ -326,7 +326,7 @@ index. Additionally, the database space used to index those public files
is really minimal (0.03% as shown in Table 1) and the number of
potential users in a system is very reduced. In the case of removable
storage files, that will be treated as public files. The solution for
-indexing and thumbnailing will be covered in [][Indexing database on removable device].
+indexing and thumbnailing will be covered in [Indexing database on removable device]( {{< ref "#indexing-database-on-removable-device" >}} ).
Another drawback is the extra processing required to index the public
contents for each user. There are also some risks about overloading too
@@ -393,7 +393,7 @@ since the updates could happen in different levels:
ALTER TABLE directly in SQLite, but this requires some custom coding
to be done and it is very complex to handle all the cases in
ontology changes. The last time the Tracker database version was
- changed was in version 0.9.38 (February 2011). See [][Tracker storage].
+ changed was in version 0.9.38 (February 2011). See [Tracker storage]( {{< ref "#tracker-storage" >}} ).
It is clear that changes in the Tracker database version is a larger
risk than changes in SQLite. Let us analyze various scenarios:
@@ -424,7 +424,7 @@ what type of data it is (generated data vs user data), and what
solutions are possible to keep the data (either implementing ad-hoc
tools to migrate data or make use of already available tools).
-See more details on Tracker Journal in [][Tracker storage].
+See more details on Tracker Journal in [Tracker storage]( {{< ref "#tracker-storage" >}} ).
**Status**. Satisfied.
@@ -520,7 +520,7 @@ to explicitly give priority to certain operations or use cases. Another
way would be a heuristic way based on recent queries done to the media
framework. This automatic approach although initially interesting looks
a bit risky, as there could be unpredictable interactions between
-applications. See [][Tracker scheduling] for more details on
+applications. See [Tracker scheduling]( {{< ref "#tracker-scheduling" >}} ) for more details on
how Tracker Scheduling works in the upstream version.
The following illustration shows an overview of how the scheduling
@@ -538,7 +538,7 @@ regarding the type of tasks and their priority, as well as test for
other ideas during the development. Requirement R12 has more details
about the abstraction of different types of tasks in the queues.
-
+
#### Media Content Counters
@@ -702,7 +702,7 @@ schedulers to keep track of the thumbnailing requests with different
priorities, it will be Tracker who takes care of the scheduling.
Thumbnail calculation is particularly expensive in CPU and storage
-resources. See the table in [][Thumbnail management] for
+resources. See the table in [Thumbnail management]( {{< ref "#thumbnail-management" >}} ) for
more detailed information.
**Status**. Satisfied.
@@ -721,7 +721,7 @@ it dependent on the number of cores in the system depending on Apertis'
needs. Additionally there is support to adjust the amount of work to do
concurrently, in order to avoid overloading the system. This is set by
the throttle parameter, which basically allows to specify how many
-extract operations can be carried per second (see [][Tracker miner]
+extract operations can be carried per second (see [Tracker miner]( {{< ref "#tracker-miner" >}} )
for more details on throttle and scheduler priority).
The operations handled by the scheduler have small granularity (a single
@@ -861,7 +861,7 @@ REST based interface.
**Solution.** With few exceptions, like **libgdata** for Google Data
Protocol, there are not many good options in FOSS to access specific
media source online providers. However, in the worst case scenario we
-could use librest and libsoup, which are described in [][Librest and Libsoup].
+could use librest and libsoup, which are described in [Librest and Libsoup]( {{< ref "#librest-and-libsoup" >}} ).
**Status.** Satisfied.
@@ -946,9 +946,9 @@ maintainers.
This chapter is focused on describing the **current status** of the
various technologies, without really including the specific additions or
modifications discussed on the requirements, which are covered in
-[][Solution]. Therefore, some of the technologies do not fully
+ [Solution]( {{< ref "#solution" >}} ). Therefore, some of the technologies do not fully
obey the requirements yet in its current status, the modifications or
-additions needed to make them work as desired are described on [][Solution].
+additions needed to make them work as desired are described on [Solution]( {{< ref "#solution" >}} ).
### Tracker
@@ -1013,7 +1013,7 @@ done as well as some enhancements and improvements, but nothing really
substantial. The performance of several components, specially the
Tracker filesystem miner has improved in the 0.12 release. The
limitations of Tracker are exposed in the context of the requirements in
-[][Solution].
+ [Solution]( {{< ref "#solution" >}} ).
The preferences for each Tracker component can be managed through
GSettings, although there is also a UI application which is not
@@ -1024,7 +1024,7 @@ interesting in the scope of this project (tracker-preferences).
The Tracker storage is divided in several parts as shown in the
following illustration.
-
+
- The public **libtracker-sparql** is the API layer used by the
applications to access the Tracker storage using SPARQL. Internally,
@@ -1204,7 +1204,7 @@ in this document, since there is no requirement for it in this project.
See a general overview in the following illustration.
-
+
#### **Tracker Extract**
@@ -1472,7 +1472,7 @@ See the following illustration for an overview of the Grilo Architecture.
Note the boxes with grey background are not going to be used in the
context of the Apertis project.
-
+
#### Grilo Media Source Plugins
@@ -1650,8 +1650,8 @@ A: No, the Tracker scheduler will manage all metadata indexing
operations in internal queues, so prioritization will just change the
sorting of the metadata indexing operations, but not the overall system
load. Note the scheduling system proposed in this document is not
-implemented in Tracker yet. See [][Indexing scheduling] and
-[][Tracker scheduling] for more details on prioritization and Tracker
+implemented in Tracker yet. See [Indexing scheduling]( {{< ref "#indexing-scheduling" >}} ) and
+ [Tracker scheduling]( {{< ref "#tracker-scheduling" >}} ) for more details on prioritization and Tracker
scheduling.
##### Q: How does the system know when to renew thumbnails ?
@@ -1682,7 +1682,7 @@ documentation.
##### Q: How the video thumbnailing works to avoid black video frames or uninteresting frames in general ?
-A: From [][Thumbnail management]: "Video thumbnails can be
+A: From [Thumbnail management]( {{< ref "#thumbnail-management" >}} ): "Video thumbnails can be
generated using the GStreamer thumbnailing plugin. This plugin already
provides an heuristic method to extract the thumbnail from a video
stream, by selecting a frame with a wide distribution of colors (to
@@ -1737,7 +1737,7 @@ devices.
A: This and other questions on system robustness will be answered on a
separate document focused on system robustness. Anyway, please see
-chapter [][Indexing database on removable device] for an advance of
+chapter [Indexing database on removable device]( {{< ref "#indexing-database-on-removable-device" >}} ) for an advance of
some issues regarding USB flash devices.
##### Q: How a media file from a USB Flash device is identified ?
diff --git a/content/designs/multimedia.md b/content/designs/multimedia.md
index ce9b712795c9f636f4cd039497b533dcd05aeadb..4ae6927a3473c90ee65ca9a7a114d813074aa220 100644
--- a/content/designs/multimedia.md
+++ b/content/designs/multimedia.md
@@ -64,7 +64,7 @@ which will offer the following features:
- Widely adopted by a variety of libraries, applications and systems
In addition, this system needs to be able to handle the requirements
-specified in [][Hardware accelerated media rendering].
+specified in [Hardware accelerated media rendering]( {{< ref "#hardware-accelerated-media-rendering" >}} ).
### Progressive download and buffered playback
@@ -104,7 +104,7 @@ the system.
### Video playback on boot
Apertis requires the capability to show a video playback during boot.
-This shares some points with the section [][Camera display on boot]
+This shares some points with the section [Camera display on boot]( {{< ref "#camera-display-on-boot" >}} )
regarding the requirements, the implementation, and risks and concerns.
Collabora has some freedom here to restrict the fps, codecs,
resolutions, quality of the video to be playback in order to be able to
@@ -458,7 +458,7 @@ to effectively be used on incoming traffic. The results in the example
setup shown below (with eth0 being a physical interface and ifb0 the
accompanying virtual interface).
-
+
To demonstrate the functionality as describe above a simple
demonstration media application using Gstreamer will be written that
diff --git a/content/designs/multiuser-transactional-switching.md b/content/designs/multiuser-transactional-switching.md
index 3eb955bb7980315c6feb2e781593cccc0fa2b5b5..5eac13874882fe09112bc46c9d5b13c3d0e86ecd 100644
--- a/content/designs/multiuser-transactional-switching.md
+++ b/content/designs/multiuser-transactional-switching.md
@@ -28,7 +28,7 @@ trade-offs such as not allowing user switching in runtime, if
implementing an ideal user experience for this feature would be too
onerous or only possible with a sub-par experience. The amount of
customization allowed would then be reduced to account for this design
-restriction, as discussed in [][Limiting customizability as a trade-off]
+restriction, as discussed in [Limiting customizability as a trade-off]( {{< ref "#limiting-customizability-as-a-trade-off" >}} )
### Terminology
@@ -235,7 +235,7 @@ on his behalf, not Diana's.
#### Cancelling the transaction
-Assume that the preconditions and events of use case [][Switching for a transaction: access to non-driver's private data] have
+Assume that the preconditions and events of use case [Switching for a transaction: access to non-driver's private data]( {{< ref "#switching-for-a-transaction-access-to-non-driver's-private-data" >}} ) have
occurred. While trying to find Fred's address, Peter is distracted
(perhaps by a call on a phone not connected with the car) and does not
continue to interact with the HMI.
@@ -255,7 +255,7 @@ touchscreen gesture).
##### Diana's “last-used†state is restored
The foreground application, the set of background applications, and all of their states
-should be identical to how they were at the beginning of [][Switching for a transaction: access to non-driver's private data].
+should be identical to how they were at the beginning of [Switching for a transaction: access to non-driver's private data]( {{< ref "#switching-for-a-transaction-access-to-non-driver's-private-data" >}} ).
It is as if the “transaction†had never happened.
*Comments:* Returning to the last-used state is important for a variant
@@ -279,7 +279,7 @@ offering actions “switch back to Diana†and “stay as Peterâ€.
Driver Diana starts to look for information on a web page, then asks the
passenger Peter to take over so that she can concentrate on driving.
-Peter wishes to authenticate as himself (as in [][Switching for a transaction: access to non-driver's private data]) so that
+Peter wishes to authenticate as himself (as in [Switching for a transaction: access to non-driver's private data]( {{< ref "#switching-for-a-transaction-access-to-non-driver's-private-data" >}} )) so that
he can use his own display preferences, bookmarks, etc.
##### State transfer
@@ -343,7 +343,7 @@ to set privacy expectations via UI design.
##### Alternative model
-The alternative model described in [][Alternative model] would
+The alternative model described in [Alternative model]( {{< ref "#alternative-model" >}} ) would
avoid any privacy concerns, but does inherit the same issues as in
and is not recommended.
@@ -363,12 +363,12 @@ user-specific (see the Requirements section of the Multiuser Design
document).
If playlists are considered to be private, Peter must authenticate and
-switch to his own user context, as in scenarios [][Switching for a transaction: access to non-driver's private data]
-and [][Switching user, maintaining state – web], to locate his own playlist.
+switch to his own user context, as in scenarios [Switching for a transaction: access to non-driver's private data]( {{< ref "#switching-for-a-transaction-access-to-non-driver's-private-data" >}} )
+and [Switching user, maintaining state – web]( {{< ref "#switching-user-maintaining-state--web" >}} ), to locate his own playlist.
If playlists are not considered to be private, Peter may either switch
to his own user context, or locate the playlist while remaining in
-Diana's configuration as in [][Passenger acts on behalf of driver access to drivers private data] (for instance, the music
+Diana's configuration as in [Passenger acts on behalf of driver access to drivers private data]( {{< ref "#passenger-acts-on-behalf-of-driver-access-to-drivers-private-data" >}} ) (for instance, the music
player could show an unobtrusive “Peter's playlists†folder alongside
Diana's own playlists).
@@ -382,7 +382,7 @@ In practice, whether Peter will actually switch users in order to do
this seems likely to depend on which he finds more irritating – using an
unfamiliar user interface, or authenticating to switch user? – and on
whether he intends to do other things “as himself†after finding the
-song. Remaining in Diana's configuration is covered by [][Passenger acts on behalf of driver access to drivers private data],
+song. Remaining in Diana's configuration is covered by [Passenger acts on behalf of driver access to drivers private data]( {{< ref "#passenger-acts-on-behalf-of-driver-access-to-drivers-private-data" >}} ),
so we assume here that he does switch.
##### Active app remains active
@@ -402,21 +402,21 @@ browser (e.g. currently viewed album) is preserved.
Peter finds
the appropriate playlist, queues the song for playing and stops using
the Apertis system. If he opts to use a similar “send...†option to
-return control of the Apertis system (as in scenario [][Switching user, maintaining state – web]), the state
+return control of the Apertis system (as in scenario [Switching user, maintaining state – web]( {{< ref "#switching-user-maintaining-state--web" >}} )), the state
in which Peter was viewing the media library browser is preserved, i.e.
the playlist remains displayed. If he merely switches back (“cancellingâ€
-the transaction as in scenario [][Cancelling the transaction]), the media player returns to the
+the transaction as in scenario [Cancelling the transaction]( {{< ref "#cancelling-the-transaction" >}} )), the media player returns to the
state that was saved as part of Diana's session during point **a**.
##### Alternative model:
-The alternative model described in [][Alternative model] would
+The alternative model described in [Alternative model]( {{< ref "#alternative-model" >}} ) would
naturally satisfy points **b**, **c**, **d** and **e**, but would not
satisfy point **a** unless playlists are not considered to be private.
#### Switching user, maintaining state – unknown app
-In a situation similar to [][Switching for a transaction: access to non-driver's private data], driver Diana starts to look
+In a situation similar to [Switching for a transaction: access to non-driver's private data]( {{< ref "#switching-for-a-transaction-access-to-non-driver's-private-data" >}} ), driver Diana starts to look
for a particular item in an arbitrary third-party app not specifically
known to the system (e.g. a restaurant guide), then asks passenger Peter
to take over.
@@ -432,7 +432,7 @@ and use his own configuration to find it.
The restaurant guide should still be
the active app after Peter has switched to his own user context. Like
-[][Switching user, maintaining state – music], but unlike the “user switching†scenario described in
+ [Switching user, maintaining state – music]( {{< ref "#switching-user-maintaining-state--music" >}} ), but unlike the “user switching†scenario described in
the Multiuser Design document, the other apps that were running last
time Peter used the car are *not* started.
@@ -460,18 +460,18 @@ her login credentials must not be transferred to Peter.
If Peter “sends
back†the state in which he was viewing the restaurant guide, similar to
-scenario [][Switching user, maintaining state – web], then that state is seen in Diana's instance of the app.
+scenario [Switching user, maintaining state – web]( {{< ref "#switching-user-maintaining-state--web" >}} ), then that state is seen in Diana's instance of the app.
##### Cancelling the transaction restores previous state
If Peter
merely cancels the transaction and lets the system return to Diana,
-similar to [][Cancelling the transaction], then the state in which the app was saved
+similar to [Cancelling the transaction]( {{< ref "#cancelling-the-transaction" >}} ), then the state in which the app was saved
before point **a** is restored.
##### Alternative model:
-The alternative model described in [][Alternative model] would
+The alternative model described in [Alternative model]( {{< ref "#alternative-model" >}} ) would
naturally satisfy all these points except the first half of the first,
unless favourite restaurants are not considered to be private.
@@ -485,8 +485,8 @@ any state to another user under any circumstances, for example a
saved-password manager or an online banking app.
Suppose Alice attempts to transfer state to another user Bob, as in
-[][Switching for a transaction: access to non-driver's private data],
-[][Switching user, maintaining state – web] etc.
+ [Switching for a transaction: access to non-driver's private data]( {{< ref "#switching-for-a-transaction-access-to-non-driver's-private-data" >}} ),
+ [Switching user, maintaining state – web]( {{< ref "#switching-user-maintaining-state--web" >}} ) etc.
##### State transfer does not occur
@@ -508,11 +508,11 @@ an unrecognized gesture, and a recognized gesture that did not result in
an action in this specific case.
*Comment*: this does not arise when cancelling a transaction as in
-[][Cancelling the transaction], because that action does not transfer state in any case.
+ [Cancelling the transaction]( {{< ref "#cancelling-the-transaction" >}} ), because that action does not transfer state in any case.
#### Switching user, maintaining state – missing app
-Similar to [][Switching user, maintaining state – unknown app], driver Diana starts a restaurant guide app, then asks
+Similar to [Switching user, maintaining state – unknown app]( {{< ref "#switching-user-maintaining-state--unknown-app" >}} ), driver Diana starts a restaurant guide app, then asks
Peter to take over. This time, suppose that Peter has not installed the
restaurant guide, so the system will not be able to reproduce the
current state for Peter.
@@ -556,10 +556,10 @@ installation procedure. If Peter chooses to install the relevant app,
the state transferred from Diana should be inserted into the “newly
installed†app. If Peter does not install the relevant app (for example
because he does not agree to an EULA or OS permissions request), the
-transaction should be cancelled (as in [][Cancelling the transaction]).
+transaction should be cancelled (as in [Cancelling the transaction]( {{< ref "#cancelling-the-transaction" >}} )).
*Comments*: as with the previous scenario, this scenario cannot occur
-when cancelling a transaction as in [][Cancelling the transaction], because that action
+when cancelling a transaction as in [Cancelling the transaction]( {{< ref "#cancelling-the-transaction" >}} ), because that action
does not transfer state in any case.
### Technical considerations
@@ -644,7 +644,7 @@ user's session is resumed.
If the first user's session is not frozen completely, then services
running outside the user sessions, such as the media player (see
-[][Switching users should not disturb some of the core functionality such as music playing] below), would need to deal with the fact that there are now
+ [Switching users should not disturb some of the core functionality such as music playing]( {{< ref "#switching-users-should-not-disturb-some-of-the-core-functionality-such-as-music-playing" >}} ) below), would need to deal with the fact that there are now
potentially two controlling user interfaces and handle multiple
connections gracefully.
@@ -706,14 +706,14 @@ This topic is discussed in the Multiuser and Applications design
documents. The only aspect directly relevant to this particular document
is that the same “save state†step that would be done during shutdown
should be performed when switching away from a user, so that the saved
-state can be reloaded for use cases such as scenario [][Cancelling the transaction].
+state can be reloaded for use cases such as scenario [Cancelling the transaction]( {{< ref "#cancelling-the-transaction" >}} ).
### When switching users, open applications must remain open
This requirement exists to enable use cases in which the driver asks a
passenger who is also a user of the system to perform some task (
-[][Switching user, maintaining state – web], [][Switching user, maintaining state – music],
-[][Switching user, maintaining state – unknown app] and [][Switching user, maintaining state – missing app]
+ [Switching user, maintaining state – web]( {{< ref "#switching-user-maintaining-state--web" >}} ), [Switching user, maintaining state – music]( {{< ref "#switching-user-maintaining-state--music" >}} ),
+ [Switching user, maintaining state – unknown app]( {{< ref "#switching-user-maintaining-state--unknown-app" >}} ) and [Switching user, maintaining state – missing app]( {{< ref "#switching-user-maintaining-state--missing-app" >}} )
are examples of this category). This passenger would log in, but at least part of the
state of the driver's session would remain.
@@ -727,7 +727,7 @@ We see three possible ways to satisfy these use cases:
- Do not transfer any state
-In some use cases such as [][Cancelling the transaction] and [][App declines to transfer state],
+In some use cases such as [Cancelling the transaction]( {{< ref "#cancelling-the-transaction" >}} ) and [App declines to transfer state]( {{< ref "#app-declines-to-transfer-state" >}} ),
having the same applications
open after a switch is not a desirable user experience. It is not
necessarily true that the user would like to use, for instance, the
@@ -775,7 +775,7 @@ and privacy concerns of transferring state when it is not desired.
We do not recommend the alternative model in which the superficial
appearance of the passenger's preferences is applied to processes that
continue to run with access to the driver's personal data (as outlined
-in [][Alternative model]), since that approach seems likely to lead to users' privacy
+in [Alternative model]( {{< ref "#alternative-model" >}} )), since that approach seems likely to lead to users' privacy
expectations not matching the reality. This applies to both the driver's
privacy (it is not entirely obvious that the passenger can still access
the driver's private data) and the passenger's privacy (for instance, it
@@ -882,7 +882,7 @@ to be considered carefully.
## Recommendations summary
-As discussed in [][Multiple users should be able to use the system though not concurrently],
+As discussed in [Multiple users should be able to use the system though not concurrently]( {{< ref "#multiple-users-should-be-able-to-use-the-system-though-not-concurrently" >}} ),
Collabora recommends having one UNIX user
account ID (uid) per user. The first user to be registered in a new
system must be able to perform administration tasks such as system
@@ -899,14 +899,14 @@ considered for premium cars with greater computing resources available.
Services that need to stay running after a user switch should have their
background functionality split from their UIs, as discussed in section
-[][Switching users should not disturb some of the core functionality such as music playing];
+ [Switching users should not disturb some of the core functionality such as music playing]( {{< ref "#switching-users-should-not-disturb-some-of-the-core-functionality-such-as-music-playing" >}} );
they can either run as a different UNIX user account ID – a “system
service†– or be a specially flagged “user service†that is not
terminated with the rest of the session.
Collabora recommends against trying to have a login mode that moves the
entire session state from the current user to the user that is logging
-in, as described in [][When switching users open applications must remain open].
+in, as described in [When switching users open applications must remain open]( {{< ref "#when-switching-users-open-applications-must-remain-open" >}} ).
To satisfy use cases in which the
current state of one user's application is sent to another user's
instance of the same application, it would be sufficient to have that
diff --git a/content/designs/multiuser.md b/content/designs/multiuser.md
index 4ce44859ac1fe63854547e0523a83d38ef533df2..ca3dc57e9f7661547e6aa04fddfc3080181ccf55 100644
--- a/content/designs/multiuser.md
+++ b/content/designs/multiuser.md
@@ -143,7 +143,7 @@ disambiguation is needed, we will refer to this as a *logind seat*.
### Fast user switching
Many operating systems have the concept of *fast user switching*, which
-is described in [][“Fast user switchingâ€: switching user without logging out].
+is described in [“Fast user switchingâ€: switching user without logging out]( {{< ref "#fast-user-switching-switching-user-without-logging-out" >}} ).
Following common usage, this document reserves the term “fast user switching†to refer to that
particular multi-user model, even if some other model might be equally
fast or faster in practice.
@@ -168,7 +168,7 @@ multi-user systems.
- When the user logs in to a newly started system, they should find
the same applications they had left open last time they shut down
- the system, and in the same state. See [][Returning to previous state]
+ the system, and in the same state. See [Returning to previous state]( {{< ref "#returning-to-previous-state" >}} )
for discussion of this topic.
- Some data is private to each user. Depending on the specific set of
@@ -198,7 +198,7 @@ multi-user systems.
- Depending on the specific set of requirements, switching users at
runtime could be supported. Where it exists, this shall be performed
with a smooth transition, with no visual flickering. User switching
- should not take more than 5 seconds. See [][Switching between users]
+ should not take more than 5 seconds. See [Switching between users]( {{< ref "#switching-between-users" >}} )
for discussion of this topic.
- A subset of features are considered to be core functionality, and
@@ -206,7 +206,7 @@ multi-user systems.
available before, during and after any transition between users. The
set of core functionality could vary by device; in this document we
mainly use music playing and navigation as examples of this
- category. See [][Preserving “core†functionality across user-switching]
+ category. See [Preserving “core†functionality across user-switching]( {{< ref "#preserving-core-functionality-across-user-switching" >}} )
for further discussion of this topic.
- The subset of features that are not disturbed while switching
@@ -214,7 +214,7 @@ multi-user systems.
considered to be “part of the operating systemâ€. For example, it
should be possible to place a user-installable player for a
third-party music streaming service such as Spotify or last.fm in
- this category. Again, see [][Preserving “core†functionality across user-switching].
+ this category. Again, see [Preserving “core†functionality across user-switching]( {{< ref "#preserving-core-functionality-across-user-switching" >}} ).
- Depending on the specific set of requirements, peripheral hardware
devices such as USB storage devices and paired Bluetooth devices
@@ -264,7 +264,7 @@ Another possibility for sharing data is that playlists within a shared
media library could appear as an unobtrusive “Bob's playlists†folder in
other users' menus, if desired.
-As discussed in [][Levels of protection between users], the level of privacy and integrity
+As discussed in [Levels of protection between users]( {{< ref "#levels-of-protection-between-users" >}} ), the level of privacy and integrity
protection between users can vary according to OEM and consumer
requirements; this could influence how user-specific data is
categorized.
@@ -285,7 +285,7 @@ authenticate themselves to a trusted HMI component, for instance by:
- simply selecting a user from a menu (choice of user, but no
meaningful authentication, similar to one of the cases described in
- [][Switchable profiles without privacy])
+ [Switchable profiles without privacy]( {{< ref "#switchable-profiles-without-privacy" >}} ))
The exact authentication mechanism depends on manufacturer and user
requirements, and is outside the scope of this document: this document
@@ -320,7 +320,7 @@ and reads the BBC News website in the browser app while stopped at
motorway services.
**a. Last-used mode**: The next time Alice starts the car and
-authenticates as herself (see [][Authentication]), the podcast and email apps
+authenticates as herself (see [Authentication]( {{< ref "#authentication" >}} )), the podcast and email apps
should resume in the same state they were in when she shut the system
down on Monday, and the HMI configuration should reflect her preferences
(the red theme should be used, etc.). Similarly, the next time Bob
@@ -338,7 +338,7 @@ starts the web browser, even if Alice deliberately looks for them.
**a. User switching**: Bob is currently using the HMI to read Twitter,
and Alice wants to check her email. Neither is currently driving. Alice
-should be able to authenticate in some way (see [][Authentication]), switching
+should be able to authenticate in some way (see [Authentication]( {{< ref "#authentication" >}} )), switching
the HMI to have Alice as its current user. When she has finished, Bob
should be able to switch the HMI back so he is the current user again,
and continue to read Twitter.
@@ -480,7 +480,7 @@ display manager terminates the X server, and starts a new X server for
the next login prompt.
Systems which offer this model can easily support the simpler models
-from [][Switchable profiles without privacy] as trivial cases of this model: they can implement the
+from [Switchable profiles without privacy]( {{< ref "#switchable-profiles-without-privacy" >}} ) as trivial cases of this model: they can implement the
PlayStation 3-like model by omitting the authentication step after
choosing a user, or the Windows 95-like model by giving each authorized
user access permissions for other users' files.
@@ -509,16 +509,16 @@ screensaver if required. When a user logs out, their session is replaced
by a login prompt at which any user can log in.
Designers typically treat this model as a superset of the simpler model
-in [][Basic multi-user: log out, log in as another user]:
+in [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} ):
in practice, implementations of “fast user switchingâ€
also offer the non-concurrent log-out/log-in arrangement as a trivial
-case. Similarly, as in [][Basic multi-user: log out, log in as another user],
+case. Similarly, as in [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} ),
implementations of this model can
-easily support the models from [][Switchable profiles without privacy] as trivial cases.
+easily support the models from [Switchable profiles without privacy]( {{< ref "#switchable-profiles-without-privacy" >}} ) as trivial cases.
In GNOME's GDM display manager, the first session takes over the X
server originally used for the login prompt, the same as in
-[][Basic multi-user: log out, log in as another user]:;
+ [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} ):;
this runs on a Linux virtual console, traditionally tty7. The
“Switch User...†option causes the display manager to run a new X
server on a different virtual console, typically tty8, and switch to it;
@@ -552,16 +552,16 @@ cause Bob's session to appear slow.
#### Multi-user desktops with multi-seat support
Some systems, in particular the systemd-logind component used in
-Apertis, can be used to extend the model in [][Basic multi-user: log out, log in as another user] by offering
-several so-called “seats†as defined in [][Multi-seat logind seats]. A logind seat is a
+Apertis, can be used to extend the model in [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} ) by offering
+several so-called “seats†as defined in [Multi-seat logind seats]( {{< ref "#multi-seat-logind-seats" >}} ). A logind seat is a
collection of display and input devices intended to be used by a single
-user, offering the equivalent of section [][Basic multi-user: log out, log in as another user] independently on each
+user, offering the equivalent of section [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} ) independently on each
logind seat. Similarly, a system can offer “fast user switchingâ€
-([][“Fast user switchingâ€: switching user without logging out]) on some or all of the available logind seats.
+( [“Fast user switchingâ€: switching user without logging out]( {{< ref "#fast-user-switching-switching-user-without-logging-out" >}} )) on some or all of the available logind seats.
GNOME's GDM display manager switches between virtual consoles on the
-first logind seat, in exactly the same way as section [][“Fast user switchingâ€: switching user without logging out]. On the
-second and subsequent logind seats, it behaves as described in [][Basic multi-user: log out, log in as another user],
+first logind seat, in exactly the same way as section [“Fast user switchingâ€: switching user without logging out]( {{< ref "#fast-user-switching-switching-user-without-logging-out" >}} ). On the
+second and subsequent logind seats, it behaves as described in [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} ),
with this logind seat's X server remaining visible regardless of the
current virtual console, and does not offer “fast user switchingâ€.
@@ -602,11 +602,11 @@ lock screen, so user switching is a matter of locking the screen (which
can be done through the 'quick settings' menu, available in the status
bar) and tapping the desired user.
-From a user interface perspective, this resembles [][“Fast user switchingâ€: switching user without logging out]
+From a user interface perspective, this resembles [“Fast user switchingâ€: switching user without logging out]( {{< ref "#fast-user-switching-switching-user-without-logging-out" >}} )
on typical desktop operating systems.
However, as an implementation detail, each user's apps are terminated
when user switching occurs, so the actual implementation is closer to
-the “log out / log back in†model (section [][Basic multi-user: log out, log in as another user]).
+the “log out / log back in†model (section [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} )).
Some settings are global to the device, including Wi-Fi networks. All
users can change these settings, apparently, and those changes will
@@ -637,7 +637,7 @@ user's home directory, contrasting with the centralized app storage used
“behind the scenes†in this design document and in Android.
The Tizen model is designed for a “multi-seat†environment as described
-in [][Multi-user desktops with multi-seat support],
+in [Multi-user desktops with multi-seat support]( {{< ref "#multi-user-desktops-with-multi-seat-support" >}} ),
where several sets of grouped devices (a display, its attached
touchscreen input device, and perhaps USB sockets and/or a headphone
jack located near that display) are all attached to the same computer as
@@ -651,7 +651,7 @@ screen to another, following a user who moves from one seat to another.
In the Tizen model, all users share a single compositor, which manages
all seats' displays and input devices, resulting in the compositor being
required to act as part of the TCB for security between users (see
-[][Trusted components]). As discussed further in [][Graphical user interface and input],
+ [Trusted components]( {{< ref "#trusted-components" >}} )). As discussed further in [Graphical user interface and input]( {{< ref "#graphical-user-interface-and-input" >}} ),
we do not recommend this approach while using X11 for GUI services.
There is a single privileged user in the Tizen system, and only that
@@ -714,8 +714,8 @@ multi-user system, this implies various more concrete principles, such
There is a spectrum of possible sets of requirements for privacy and
integrity protection between users: a strongly protected model similar
-to the one detailed in section [][Typical desktop multi-user], a model with no protection at all as
-described in [][Switchable profiles without privacy], or anything in between (e.g. with protection
+to the one detailed in section [Typical desktop multi-user]( {{< ref "#typical-desktop-multi-user" >}} ), a model with no protection at all as
+described in [Switchable profiles without privacy]( {{< ref "#switchable-profiles-without-privacy" >}} ), or anything in between (e.g. with protection
between users in general, but certain categories of data explicitly
shared).
@@ -839,7 +839,7 @@ We recommend this approach for Apertis.
#### Multiple uids per user
Android uses a design involving multiple uids per user, one per app or
-set of related apps, as described in [][Android 4.2+]. This allows the Linux
+set of related apps, as described in [Android 4.2+]( {{< ref "#android-42+" >}} ). This allows the Linux
kernel's privacy and integrity features to be used to protect apps from
other apps, even within a user session. However, in Apertis, this
advantage is redundant, since we already use a different kernel feature
@@ -1001,14 +1001,14 @@ be part of the TCB for security between users.
One possible model is to have a single compositor which starts on boot,
runs until shutdown, and is directly responsible for compositing all
application surfaces. This model would be appropriate if there is only
-one uid shared by all users as described in section [][Sharing one uid between all users], since in that
+one uid shared by all users as described in section [Sharing one uid between all users]( {{< ref "#sharing-one-uid-between-all-users" >}} ), since in that
model there is no OS-level isolation between user accounts in any case.
It could potentially also be used in a design where each user has their
own uid, by running the compositor with a non-user-specific uid.
The major disadvantage of this situation is that it places the
user-level compositor into a trusted position: it would become part of
-the trusted computing base for separation between users (see [][Trusted components]).
+the trusted computing base for separation between users (see [Trusted components]( {{< ref "#trusted-components" >}} )).
Mutter is not typically used like this, and has not been designed
or audited for this use. Other compositors would need to be carefully
checked for safety for this use. As a general design principle, the less
@@ -1048,8 +1048,8 @@ system as a whole in this model.
#### Switching between compositors
The traditional design for user-switching in X, as described in
-[][Basic multi-user: log out, log in as another user] and
-[][“Fast user switchingâ€: switching user without logging out],
+ [Basic multi-user: log out, log in as another user]( {{< ref "#basic-multi-user-log-out-log-in-as-another-user" >}} ) and
+ [“Fast user switchingâ€: switching user without logging out]( {{< ref "#fast-user-switching-switching-user-without-logging-out" >}} ),
is to start a new X server for each user session and
switch between them, for instance by using the Linux kernel's “virtual
console†facility, or by dynamically attaching/detaching the X servers
@@ -1108,7 +1108,7 @@ startup and shutdown. At any given moment, either the system-level
compositor or a session compositor would be active (have control over
input and output), but never both.
-In this model, as in [][Switching between compositors],
+In this model, as in [Switching between compositors]( {{< ref "#switching-between-compositors" >}} ),
the transition between users would involve
systemd-logind revoking the old session compositor's control over the
display (“DRM master†status) and over input devices; however, instead
@@ -1117,8 +1117,8 @@ give control to a special-purpose system-level compositor which would
perform the transition, and then in turn hand over to the new session.
This system-level compositor could capture the current screen contents
as a starting point for the animated transition, if desired; as in
-[][Switching between compositors], the screen contents would cross a privilege boundary, but unlike
-[][Switching between compositors], the other side of the privilege boundary in this design is a
+ [Switching between compositors]( {{< ref "#switching-between-compositors" >}} ), the screen contents would cross a privilege boundary, but unlike
+ [Switching between compositors]( {{< ref "#switching-between-compositors" >}} ), the other side of the privilege boundary in this design is a
trusted process.
The new session compositor could be started without direct access to the
@@ -1257,7 +1257,7 @@ transition.
#### System services
-System services (as defined by [][System services]) continue to run regardless
+System services (as defined by [System services]( {{< ref "#system-services" >}} )) continue to run regardless
of what is happening in user sessions, so one possible approach is to
put “core†functionality in system services. These could be anywhere
from highly privileged to entirely unprivileged; the distinction here is
@@ -1291,10 +1291,10 @@ per-user configuration (the user part).
#### User services continuing to run
-User services (as defined by [][User services]) are inherently per-user. If
+User services (as defined by [User services]( {{< ref "#user-services" >}} )) are inherently per-user. If
the end of a user's login session terminates their GUI applications but
leaves some or all of their user services running, this could increase
-system load (as noted in section [][Switching between users]), but would make user services a
+system load (as noted in section [Switching between users]( {{< ref "#switching-between-users" >}} )), but would make user services a
suitable implementation for features that must run uninterrupted. This
could apply either in general, or with restrictions (for example, some
subset of the inactive user's user-services could continue to run,
@@ -1372,15 +1372,15 @@ design.
## Summary of recommendations
-As discussed in [][User accounts representing users within the system],
+As discussed in [User accounts representing users within the system]( {{< ref "#user-accounts-representing-users-within-the-system" >}} ),
Collabora recommends representing each user
account as a Unix user ID (uid). The first user to be registered in a
new system must be able to perform administration tasks such as system
updates, application installation, creation of new users and setting up
-permissions – that is discussed in [][Creating and managing user accounts].
+permissions – that is discussed in [Creating and managing user accounts]( {{< ref "#creating-and-managing-user-accounts" >}} ).
There is a range of possible approaches to switching between users,
-discussed in section [][Switching between users]. This document does not recommend a particular
+discussed in section [Switching between users]( {{< ref "#switching-between-users" >}} ). This document does not recommend a particular
choice from that range, since it depends on the available hardware
resources and the system's use-cases and requirements. For
budget-limited designs with significant hardware limitations, we should
@@ -1389,7 +1389,7 @@ concurrency, or if this is not acceptable, opt to leave user-switching
unsupported; for premium models with more capable hardware, the more
resource-expensive “fast user switching†approach can be considered.
-In [][Preserving “core†functionality across user-switching]
+In [Preserving “core†functionality across user-switching]( {{< ref "#preserving-core-functionality-across-user-switching" >}} )
we outline various possible approaches to ensuring that
“core functionality†is not interrupted by a user switch. Services
that need to stay running after a user switch should have their
@@ -1398,19 +1398,19 @@ different Unix user account ID – a “system service†– or be a specially
flagged “user service†that is not terminated with the rest of the
session.
-In [][Returning to previous state], Collabora recommends that applications should be
+In [Returning to previous state]( {{< ref "#returning-to-previous-state" >}} ), Collabora recommends that applications should be
handling saving and restoring of their state themselves, potentially
supported by helper SDK APIs, which means only applications written with
Apertis in mind would work. That recommendation comes from the fact that
there is no solution that would work for all applications.
Ways of having a smooth visual transition when switching users are
-discussed in section [][Graphical user interface and input]. Collabora recommends revisiting this topic
+discussed in section [Graphical user interface and input]( {{< ref "#graphical-user-interface-and-input" >}} ). Collabora recommends revisiting this topic
after Apertis' graphical user interface and input processing has been
switched from X to Wayland; our provisional recommendation is to
implement a hand-off procedure between compositors running under the
-appropriate user ID, either with ([][Switching between compositors with a system compositor] or without (section
-[][Switching between compositors]) an intermediate switch to a system compositor.
+appropriate user ID, either with ( [Switching between compositors with a system compositor]( {{< ref "#switching-between-compositors-with-a-system-compositor" >}} ) or without (section
+ [Switching between compositors]( {{< ref "#switching-between-compositors" >}} )) an intermediate switch to a system compositor.
[Android 4.2]: http://developer.android.com/about/versions/jelly-bean.html#android-42
diff --git a/content/designs/op-tee.md b/content/designs/op-tee.md
index fb84a4ff5de1e3cf8a1e32a3f3dd8cc4bbe308cf..3fb7735883daedd61d2c3cb34205e40a66cf0e7c 100644
--- a/content/designs/op-tee.md
+++ b/content/designs/op-tee.md
@@ -13,7 +13,7 @@ A typical use case is enabling the decryption of protected content in such a way
Another use for strong security is the protection of authentication keys.
By shielding such keys within these strong security measures, it becomes much harder for the keys to be stolen and be used to impersonate the legitimate user.
-
+
In the above example, when requesting access to the cloud service, the service returns a challenge response, which needs to be signed using [asymmetric cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography).
The Apertis application requests that functionality in the secure environment sign the challenge using a private key that it stores securely.
@@ -27,7 +27,7 @@ ARM provides an implementation of such security mechanisms, known as [ARM TrustZ
## System Architecture
-
+
A TEE exists as a separate environment running in parallel with the main operating system.
At boot, both of these environments need to be loaded and initialised, this is achieved by running special boot firmware which enables the TrustZone security features and loads the required software elements.
diff --git a/content/designs/preferences-and-persistence.md b/content/designs/preferences-and-persistence.md
index 649c48ebadd85d78fa298c2ef7fb19ae47f7b5f2..4cc371577bb8425551c12ff1d9345fa49987f8b8 100644
--- a/content/designs/preferences-and-persistence.md
+++ b/content/designs/preferences-and-persistence.md
@@ -19,7 +19,7 @@ preferences in the UI.
The Applications Design, and Global Search Design documents are relevant
reading. The [Applications Design](applications.md) and
the [Global Search Design](global-search.md) reference the need for storage of persistent
-data for apps. See [][Overall architecture] for a design covering this.
+data for apps. See [Overall architecture]( {{< ref "#overall-architecture" >}} ) for a design covering this.
The [Robustness Design](robustness.md) document gives more detail on the requirements for
robustness of main storage in the face of power loss.
@@ -82,7 +82,7 @@ state of the user's pending downloads.
One distinguishing factor between preferences and persistent data is
that vendors may override the default values for preferences (see
-[][Vendor overrides]), but not for persistent data. For example, a vendor would
+ [Vendor overrides]( {{< ref "#vendor-overrides" >}} )), but not for persistent data. For example, a vendor would
not want to override information about in-progress downloads; but they
might want to override the default background image filename for a user.
@@ -173,8 +173,8 @@ be accessed by user services and system services.
As well as the value of a preference, components must be able to find
out whether the preference is writable. A preference may be read-only if
-the component doesn't have write permission for it ([][Access permissions]) or if
-it is locked down by the vendor ([](#vendor-lockdown)).
+the component doesn't have write permission for it ( [Access permissions]( {{< ref "#access-permissions" >}} )) or if
+it is locked down by the vendor [vendor lockdown]( {{< ref "#vendor-lockdown" >}} )).
This does not apply to persistent data, which is always read–write by
the (user, app) pair which owns it.
@@ -291,7 +291,7 @@ system) preferences before shipping to the end user. For example, they
may change the default background image shown to the user.
If these are supported, resetting a preference to its default value (for
-example, if doing a [][Factory reset]) must restore it to the
+example, if doing a [Factory reset]( {{< ref "#factory-reset" >}} )) must restore it to the
vendor-supplied default, rather than the Apertis default. There is no
need to be able to access the Apertis default at any time.
@@ -526,7 +526,7 @@ when the login session ends.
For secrets which are not for online accounts, or otherwise do not fit
the AccountManager pattern, Android [recommends][Android-settings-question] using the normal
-preferences API ([][Preferences]), as while preferences are not encrypted
+preferences API ( [Preferences]( {{< ref "#preferences" >}} )), as while preferences are not encrypted
in storage, they are only accessible to the application which owns them,
so cannot be stolen by other applications. However, if the sandboxing
system is compromised (potentially by an attacker with physical access
@@ -691,8 +691,7 @@ application state.
Preferences and persistent data have largely separate requirements:
preferences are small amounts of data; need to be accessed by multiple
components; will typically be read much more frequently than they are
-written; and need to support features like [][Vendor overrides] and
-[](#vendor-lockdown). Persistent data may vary from
+written; and need to support features like [Vendor overrides]( {{< ref "#vendor-overrides" >}} ) and[vendor lockdown]( {{< ref "#vendor-lockdown" >}} ). Persistent data may vary from
small to large amounts of data; will be read *and* written frequently;
in app-specific formats; and do not need to be accessed by other
components.
@@ -709,7 +708,7 @@ handled entirely separately. The following sections (6 and 7) will cover
them separately, giving our recommended approach and justifications
which refer back to the requirements (section 3).
-User secrets and passwords ([][Storage of user secrets and passwords]) have different requirements
+User secrets and passwords ( [Storage of user secrets and passwords]( {{< ref "#storage-of-user-secrets-and-passwords" >}} )) have different requirements
again:
- Confidentiality in storage (encryption).
@@ -739,7 +738,7 @@ passwords, see the [Security design document](security.md).
### Overall architecture
Access to app, user and system settings should be through the GSettings
-API, most likely backed by dconf. (Refer to [][GNOME Linux desktop] for an overview
+API, most likely backed by dconf. (Refer to [GNOME Linux desktop]( {{< ref "#gnome-linux-desktop" >}} ) for an overview
of the way GSettings and dconf fit together.) As system settings are
defined as those settings which are accessed by multiple components,
settings which are solely for the use of a single system service may be
@@ -780,7 +779,7 @@ multiple accounts, for example.
It is expected that each app will handle any upgrades to its preference
schemas, for example from one major version of the app to the next
-([][System and app bundle upgrades]). Apertis will not provide any special APIs for this. As
+( [System and app bundle upgrades]( {{< ref "#system-and-app-bundle-upgrades" >}} )). Apertis will not provide any special APIs for this. As
this is highly dependent on the structure of the preference keys an app
is storing, Apertis can provide no recommendations here. Note, however,
that GSettings is designed with upgradability in mind: new preference
@@ -797,54 +796,54 @@ bundle.
Through the use of the GSettings API, the following requirements are
automatically fulfilled:
- - [][Writability] — using g\_settings\_is\_writable()
+ - [Writability]( {{< ref "#writability" >}} ) — using g\_settings\_is\_writable()
- - [][System and app bundle upgrades] — old keys are either kept, or superseded by new
+ - [System and app bundle upgrades]( {{< ref "#system-and-app-bundle-upgrades" >}} ) — old keys are either kept, or superseded by new
keys with migrated values if their type or semantics change
- - [][Factory reset] — for individual keys, using
+ - [Factory reset]( {{< ref "#factory-reset" >}} ) — for individual keys, using
g\_settings\_reset(); support for resetting entire schemas needs to
be supported by the designs below
- - [][Abstraction level] — GSettings serves as the abstraction layer,
+ - [Abstraction level]( {{< ref "#abstraction-level" >}} ) — GSettings serves as the abstraction layer,
with the individual backends below adding no further abstractions
- - [][Transactional updates] — GSettings provides
+ - [Transactional updates]( {{< ref "#transactional-updates" >}} ) — GSettings provides
g\_settings\_delay(), g\_settings\_apply() and g\_settings\_revert()
to implement in-memory transactions which are serialised in the
backend on calling apply
- - [][Concurrency control] — g\_settings\_get() automatically returns the
+ - [Concurrency control]( {{< ref "#concurrency-control" >}} ) — g\_settings\_get() automatically returns the
default value if no user-set value exists; there is no atomic API
for setting settings
- - [][User interface] — g\_settings\_bind() can be used to bind a
+ - [User interface]( {{< ref "#user-interface" >}} ) — g\_settings\_bind() can be used to bind a
GSettings key to a particular UI widget, allowing interface UIs to
- be built easily (noting the argument in [][User interface] that preferences
+ be built easily (noting the argument in [User interface]( {{< ref "#user-interface" >}} ) that preferences
UIs should not be automatically generated)
Other requirements are fulfilled separately:
- - [][Control over user interface] — by generating preferences
+ - [Control over user interface]( {{< ref "#control-over-user-interface" >}} ) — by generating preferences
windows from GSettings schemas in the system preferences application
- ([][Searchable preferences])
+ ( [Searchable preferences]( {{< ref "#searchable-preferences" >}} ))
- - [][Rearrangeable preferences] — by hard-coding more
- behaviour in the system preferences application ([][User interface])
+ - [Rearrangeable preferences]( {{< ref "#rearrangeable-preferences" >}} ) — by hard-coding more
+ behaviour in the system preferences application ( [User interface]( {{< ref "#user-interface" >}} ))
- - [][Searchable preferences] — searching over summaries and
- descriptions in GSettings schemas ([][Security policy])
+ - [Searchable preferences]( {{< ref "#searchable-preferences" >}} ) — searching over summaries and
+ descriptions in GSettings schemas ( [Security policy]( {{< ref "#security-policy" >}} ))
- - [][Storage of user secrets and passwords] — using the
+ - [Storage of user secrets and passwords]( {{< ref "#storage-of-user-secrets-and-passwords" >}} ) — using the
freedesktop.org Secrets D-Bus API as in the Security design (section
5)
- - [](#preferences-hard-key) — implemented according to the Hard Keys
- design ([](#preferences-hard-key1))
+ -[preferences hard key]( {{< ref "#preferences-hard-key" >}} ) — implemented according to the Hard Keys
+ design [preferences hard key1]( {{< ref "#preferences-hard-key1" >}} ))
### Proxied dconf backend
-In its current state (May 2015, detailed in [][GNOME Linux desktop]), dconf does not
+In its current state (May 2015, detailed in [GNOME Linux desktop]( {{< ref "#gnome-linux-desktop" >}} )), dconf does not
support the necessary fine-grained access controls for multiple
components accessing the preferences. However, a design is being
implemented upstream to proxy access to dconf through a separate service
@@ -852,7 +851,7 @@ which imposes access controls based on AppArmor ([mostly implemented as
of January 2016][appservice]).
On the assumption that this work can be completed and integrated into
-Apertis on an appropriate timescale (see [][Summary of recommendations]),
+Apertis on an appropriate timescale (see [Summary of recommendations]( {{< ref "#summary-of-recommendations" >}} )),
this leads to a design where the dconf daemon runs as
a system service, storing all settings in one database file per default
layer:
@@ -875,7 +874,7 @@ system-db:local
All accesses to dconf would go through GSettings, and then through the
proxy service which applies AppArmor rules to restrict access to
-specific settings, implementing the chosen security policy ([][Access permissions]).
+specific settings, implementing the chosen security policy ( [Access permissions]( {{< ref "#access-permissions" >}} )).
The rules may, for example, match against settings path and the
AppArmor label of the calling process.
@@ -913,35 +912,35 @@ allowing the dconf daemon access to the database.
This design fulfills the following requirements:
- - [][Access permissions] — through use of the proxy service and
+ - [Access permissions]( {{< ref "#access-permissions" >}} ) — through use of the proxy service and
AppArmor rules
- - [][Rollback] — by rolling back the user’s per-app database
+ - [Rollback]( {{< ref "#rollback" >}} ) — by rolling back the user’s per-app database
- - [][Factory reset] — by deleting the user’s database or the user’s
+ - [Factory reset]( {{< ref "#factory-reset" >}} ) — by deleting the user’s database or the user’s
per-app database
- - [][Minimising io bandwidth] — dconf’s database design is optimised
+ - [Minimising io bandwidth]( {{< ref "#minimising-io-bandwidth" >}} ) — dconf’s database design is optimised
for this
- - [][Atomic updates] — dconf performs atomic overwrites of the
+ - [Atomic updates]( {{< ref "#atomic-updates" >}} ) — dconf performs atomic overwrites of the
database
- - [][Performance tradeoffs] — dconf is heavily optimised for reads
+ - [Performance tradeoffs]( {{< ref "#performance-tradeoffs" >}} ) — dconf is heavily optimised for reads
rather than writes
- - [][Data size tradeoffs] — dconf uses GVDB for storage, so can
+ - [Data size tradeoffs]( {{< ref "#data-size-tradeoffs" >}} ) — dconf uses GVDB for storage, so can
handle small to large amounts of data
- - [][Vendor overrides] — dconf supports vendor overrides inherently
+ - [Vendor overrides]( {{< ref "#vendor-overrides" >}} ) — dconf supports vendor overrides inherently
- - [](#vendor-lockdown) — dconf supports vendor lockdown inherently
+ -[vendor lockdown]( {{< ref "#vendor-lockdown" >}} ) — dconf supports vendor lockdown inherently
### Development backend
In the interim, we recommend that the standard dconf backend be used to
store all system, user and app settings. This will *not* allow for
-access controls to be applied to the settings ([][Access permissions]), but
+access controls to be applied to the settings ( [Access permissions]( {{< ref "#access-permissions" >}} )), but
will allow for app development against the final GSettings interface.
Once the proxied dconf backend is ready, it can be packaged and the
@@ -958,32 +957,32 @@ dconf database file.
This design fails the following requirements:
- - [][Access permissions] — **unsupported** by the current version of
+ - [Access permissions]( {{< ref "#access-permissions" >}} ) — **unsupported** by the current version of
dconf
- - [][Rollback] — **unsupported** by the current version of dconf
+ - [Rollback]( {{< ref "#rollback" >}} ) — **unsupported** by the current version of dconf
It supports the following requirements:
- - [][Factory reset] — **partially supported** by deleting the user’s
+ - [Factory reset]( {{< ref "#factory-reset" >}} ) — **partially supported** by deleting the user’s
database; resetting a (user, app) pair is not supported as all
settings are stored in the same dconf database file
- - [][Minimising io bandwidth] — dconf’s database design is optimised
+ - [Minimising io bandwidth]( {{< ref "#minimising-io-bandwidth" >}} ) — dconf’s database design is optimised
for this
- - [][Atomic updates] — dconf performs atomic overwrites of the
+ - [Atomic updates]( {{< ref "#atomic-updates" >}} ) — dconf performs atomic overwrites of the
database
- - [][Performance tradeoffs] — dconf is heavily optimised for reads
+ - [Performance tradeoffs]( {{< ref "#performance-tradeoffs" >}} ) — dconf is heavily optimised for reads
rather than writes
- - [][Data size tradeoffs] — dconf uses GVDB for storage, so can
+ - [Data size tradeoffs]( {{< ref "#data-size-tradeoffs" >}} ) — dconf uses GVDB for storage, so can
handle small to large amounts of data
- - [][Vendor overrides] — dconf supports vendor overrides inherently
+ - [Vendor overrides]( {{< ref "#vendor-overrides" >}} ) — dconf supports vendor overrides inherently
- - [](#vendor-lockdown) — dconf supports vendor lockdown inherently
+ -[vendor lockdown]( {{< ref "#vendor-lockdown" >}} ) — dconf supports vendor lockdown inherently
### Key-file backend
@@ -1032,31 +1031,31 @@ and supported indefinitely, even after changing the backend.
This design fails the following requirements:
- - [][Performance tradeoffs] — GKeyFile is **equally non-optimised**
+ - [Performance tradeoffs]( {{< ref "#performance-tradeoffs" >}} ) — GKeyFile is **equally non-optimised**
for reads and writes
- - [][Vendor overrides] — **unsupported** by GKeyFile
+ - [Vendor overrides]( {{< ref "#vendor-overrides" >}} ) — **unsupported** by GKeyFile
- - [](#vendor-lockdown) — **unsupported** by GKeyFile
+ -[vendor lockdown]( {{< ref "#vendor-lockdown" >}} ) — **unsupported** by GKeyFile
It supports the following requirements:
- - [][Access permissions] — supported by AppArmor rules on the
+ - [Access permissions]( {{< ref "#access-permissions" >}} ) — supported by AppArmor rules on the
per-schema key files
- - [][Rollback] — by snapshotting and rolling back the appropriate key
+ - [Rollback]( {{< ref "#rollback" >}} ) — by snapshotting and rolling back the appropriate key
files
- - [][Factory reset] — by deleting the appropriate key files
+ - [Factory reset]( {{< ref "#factory-reset" >}} ) — by deleting the appropriate key files
- - [][Minimising io bandwidth] — GKeyFile’s I/O bandwidth is
+ - [Minimising io bandwidth]( {{< ref "#minimising-io-bandwidth" >}} ) — GKeyFile’s I/O bandwidth is
proportional to the number of times each key file is loaded and
saved
- - [][Atomic updates] — GKeyFile performs atomic overwrites of the
+ - [Atomic updates]( {{< ref "#atomic-updates" >}} ) — GKeyFile performs atomic overwrites of the
database
- - [][Data size tradeoffs] — GKeyFile’s load and save performance is
+ - [Data size tradeoffs]( {{< ref "#data-size-tradeoffs" >}} ) — GKeyFile’s load and save performance is
proportional to the amount of data stored in the file, so it is
suitable for small amounts of data
@@ -1064,7 +1063,7 @@ It supports the following requirements:
All three potential backends enforce security policy through per-app
AppArmor rules (if they support implementing security policy at all —
-the [][Development backend], does not).
+the [Development backend]( {{< ref "#development-backend" >}} ), does not).
It is beyond the scope of this document to define how each app ships its
AppArmor rules, and how Apertis can guarantee that third-party apps
@@ -1084,7 +1083,7 @@ preferences is abstracted through GSettings).
### User interface
Different options for building preferences user interfaces need to be
-supported by the system ([][Control over user interface]):
+supported by the system ( [Control over user interface]( {{< ref "#control-over-user-interface" >}} )):
- Individual preferences embedded at different points in the
application UI.
@@ -1095,7 +1094,7 @@ supported by the system ([][Control over user interface]):
preferences for all installed applications, plus system preferences.
In all cases, we recommend that preferences are defined using GSettings
-schemas, as discussed in [][Overall architecture], and that settings are read and
+schemas, as discussed in [Overall architecture]( {{< ref "#overall-architecture" >}} ), and that settings are read and
written through the [GSettings] API. This ensures that access
control is enforced, and separates the structure of the preferences
(including types and default values) from their presentation.
@@ -1123,7 +1122,7 @@ window must be automatically generated. This is because:
However, automatically generated UIs generally give a bad user
experience, due to the limited flexibility a designer has on them, so
are suitable only for basic preferences (such as toggle switches; see
-[][Discussion of automatically generated versus manually coded preferences UIs]).
+ [Discussion of automatically generated versus manually coded preferences UIs]( {{< ref "#discussion-of-automatically-generated-versus-manually-coded-preferences-uis" >}} )).
There may be cases where an application has a particular
preference which Apertis provides no widgets suitable for editing it. In
these infrequent cases, it must be possible for the system preferences
@@ -1144,7 +1143,7 @@ displayed.
If the user selects an application, a preferences window should be
displayed which shows all the preferences in the application’s GSettings
-schema file. See [][Generating a preferences window from a GSettings schema file]
+schema file. See [Generating a preferences window from a GSettings schema file]( {{< ref "#generating-a-preferences-window-from-a-gsettings-schema-file" >}} )
for details of how this is done. Note
that if the schema file defines multiple levels of schema, they should
be presented as a hierarchy of pages, with preferences only being shown
@@ -1173,7 +1172,7 @@ preferences application.
It should support being launched with the name of a GSettings schema to
show, and it would render a preferences window from that schema (see
-[][Generating a preferences window from a GSettings schema file]).
+ [Generating a preferences window from a GSettings schema file]( {{< ref "#generating-a-preferences-window-from-a-gsettings-schema-file" >}} )).
If the schema file defines multiple levels of schema,
they should be presented as a hierarchy of pages, with preferences only
being shown on leaf pages. It is up to the vendor whether the user can
@@ -1259,7 +1258,7 @@ following rules:
corresponding \<flags\> element.
- If a key’s name attribute matches a mapping to a wizard application
- (see [][Support for custom preferences windows]) in the application’s manifest, that key should
+ (see [Support for custom preferences windows]( {{< ref "#support-for-custom-preferences-windows" >}} )) in the application’s manifest, that key should
be displayed as a menu entry which, when selected, launches the
wizard application as a new window.
@@ -1267,7 +1266,7 @@ following rules:
If an application has a particularly esoteric preference or set of
preferences which are not supported by the generated preferences UI (see
-[][Generating a preferences window from a GSettings schema file]),
+ [Generating a preferences window from a GSettings schema file]( {{< ref "#generating-a-preferences-window-from-a-gsettings-schema-file" >}} )),
it may provide a ‘wizard’ application as part of its
application bundle which allows setting those preferences (and only
those preferences). For example, this could be used to show a ‘wizard’
@@ -1298,7 +1297,7 @@ generated UI.
The wizard application must set the relevant preferences itself before
exiting, and runs with the same privileges as the rest of the
application bundle (so will only have access to that application’s
-preferences, as per [][Security policy]).
+preferences, as per [Security policy]( {{< ref "#security-policy" >}} )).
It may be necessary for the window manager to treat windows from wizard
applications specially, so that they appear more like a window which is
@@ -1310,7 +1309,7 @@ differently.
#### Searchability of preferences
To allow the system preferences application to search over all
-applications’ preferences ([][Searchable preferences]), it must load all the
+applications’ preferences ( [Searchable preferences]( {{< ref "#searchable-preferences" >}} )), it must load all the
GSettings schemas from applications whose manifests specify a schema.
Searching must be performed over the user-visible parts of the schema
(the \<summary\> and \<description\> elements), and results should be
@@ -1319,7 +1318,7 @@ System preferences should be included in the search results too.
#### Reorganising preferences
-Implementing arbitrary reorganisation of preferences ([][Rearrangeable preferences])
+Implementing arbitrary reorganisation of preferences ( [Rearrangeable preferences]( {{< ref "#rearrangeable-preferences" >}} ))
is difficult, as that requires an OEM to know the semantics of all
preferences for all possibly installable applications.
@@ -1345,19 +1344,19 @@ too much control over the appearance of a system preferences window.
#### Preferences list widget
In order to help make all preferences UIs consistent (including those
-implemented by the vendor, [][System preferences application]; and those implemented by
-application developers as wizard applications, [][Per-application preferences windows]), Apertis
+implemented by the vendor, [System preferences application]( {{< ref "#system-preferences-application" >}} ); and those implemented by
+application developers as wizard applications, [Per-application preferences windows]( {{< ref "#per-application-preferences-windows" >}} )), Apertis
should provide a standard widget which implements the conversion from
-GSettings schemas to UI as described in [][Generating a preferences window from a GSettings schema file].
+GSettings schemas to UI as described in [Generating a preferences window from a GSettings schema file]( {{< ref "#generating-a-preferences-window-from-a-gsettings-schema-file" >}} ).
This widget should accept a list of GSettings schema paths to display,
and may optionally accept a list of keys within those schemas to display
(ignoring the others), or to ignore (displaying the others); and should
display all those keys as preferences. It should implement reading and
writing the keys’ values using the GSettings API, and must assume that
-the application has permission to do so (see [][Security policy]). It must check
+the application has permission to do so (see [Security policy]( {{< ref "#security-policy" >}} )). It must check
for writability of preferences and make them insensitive if they are
-read-only (see [](#vendor-lockdown1)). It cannot give the application more
+read-only (see[vendor lockdown1]( {{< ref "#vendor-lockdown1" >}} )). It cannot give the application more
permissions than it already has.
If application developers use this widget, the vendor can ensure that
@@ -1367,8 +1366,8 @@ preferences application through the theming of the widget.
#### Vendor lockdown
If the vendor locks down a key in a GSettings schema for an application
-(or system preference) ([](#vendor-lockdown) — supported by [][Proxied dconf backend]
-and [][Development backend], but not [][Key-file backend]), that is enforced by the underlying settings service
+(or system preference) [vendor lockdown]( {{< ref "#vendor-lockdown" >}} ) — supported by [Proxied dconf backend]( {{< ref "#proxied-dconf-backend" >}} )
+and [Development backend]( {{< ref "#development-backend" >}} ), but not [Key-file backend]( {{< ref "#key-file-backend" >}} )), that is enforced by the underlying settings service
(most likely dconf), and cannot be overridden or worked around by
applications.
@@ -1377,7 +1376,7 @@ read-only (due to being locked down) in their UIs. This is typically
achieved by hiding a preference or making its widget insensitive.
Applications can use the [g_settings_is_writable] method to
determine whether a preference is read-only. Any preferences widgets
-provided by Apertis ([][Preferences list widget]) must implement this already.
+provided by Apertis ( [Preferences list widget]( {{< ref "#preferences-list-widget" >}} )) must implement this already.
If an application developer uses a custom widget to display a
preference, and forgets to check whether that preference is read-only,
@@ -1551,7 +1550,7 @@ be /Applications/*net.example.MyApp*/Storage/*username*/state/. This has
the advantage of allowing all data for a particular app to be removed by
deleting /Applications/net.example.MyApp, at the cost of not following
the XDG standard used by most existing software. This fulfils the
-factory reset requirement ([][Factory reset]).
+factory reset requirement ( [Factory reset]( {{< ref "#factory-reset" >}} )).
The former is effectively equivalent to a per-(user, app)
XDG\_CACHE\_HOME directory, and the latter to a XDG\_DATA\_HOME, as
@@ -1563,12 +1562,12 @@ security needed, as state storage is simply an interaction between an
app and the filesystem.
This approach automatically allows for rollback of persistent data
-([][Rollback]) using the normal snapshotting mechanism described in
+( [Rollback]( {{< ref "#rollback" >}} )) using the normal snapshotting mechanism described in
the Applications Design document.
As with preferences, app bundles must be in charge of upgrading their
own persistent data when the system is upgraded (or the app is upgraded)
-([][System and app bundle upgrades]). Recommendations are given in the subsections below.
+( [System and app bundle upgrades]( {{< ref "#system-and-app-bundle-upgrades" >}} )). Recommendations are given in the subsections below.
### Recommended serialisation APIs
@@ -1581,13 +1580,13 @@ Alongside, Apertis should provide guidelines to app developers to allow
them to choose an appropriate serialisation API, and avoid common
problems in serialisation:
- - minimise writes to main storage ([][Minimising io bandwidth]);
+ - minimise writes to main storage ( [Minimising io bandwidth]( {{< ref "#minimising-io-bandwidth" >}} ));
- ensure all updates to stored state are atomic (requirement
- [][Atomic updates]); and
+ [Atomic updates]( {{< ref "#atomic-updates" >}} )); and
- ensure transactions are used for groups of updates where appropriate
- ([][Transactional updates]).
+ ( [Transactional updates]( {{< ref "#transactional-updates" >}} )).
> Atomic in the sense that either the old or new states are stored in
> entirety, rather than some intermediate state, if power is lost
@@ -1633,7 +1632,7 @@ small to large amounts of data which are read much more frequently than
they are written. This is what dconf uses for storage.
All updates to a GVDB file are atomic, as it uses the same
-atomic-overwrite technique as [][GKeyFile]. Transactions are
+atomic-overwrite technique as [GKeyFile]( {{< ref "#gkeyfile" >}} ). Transactions are
supported similarly — by writing out the updated database or discarding
```
@@ -1644,7 +1643,7 @@ done when explicitly requested by the app.
GVDB supports per-file versioning (though this is not currently exposed
in the public API). This can be used for handling system upgrades
-([][System and app bundle upgrades]) — the database must be explicitly migrated from an old
+( [System and app bundle upgrades]( {{< ref "#system-and-app-bundle-upgrades" >}} )) — the database must be explicitly migrated from an old
version to a new version when an upgraded app is first
started.
@@ -1690,7 +1689,7 @@ If using GObjects to represent entries in an SQLite database, the
This is **not** recommended. It is an abstraction layer over multiple
SQL database implementations, allowing apps to access remote SQL
-databases. In almost all cases, directly using [][Sqlite] is a more
+databases. In almost all cases, directly using [Sqlite]( {{< ref "#sqlite" >}} ) is a more
appropriate choice.
### When to save persistent data
@@ -1723,59 +1722,59 @@ Design document.
As discussed in the above sections, we recommend:
- Splitting preferences, persistent data storage and confidential data
- storage ([][Approach]).
+ storage ( [Approach]( {{< ref "#approach" >}} )).
- - Providing one API for preferences: GSettings ([][Overall architecture]).
+ - Providing one API for preferences: GSettings ( [Overall architecture]( {{< ref "#overall-architecture" >}} )).
- Apps provide a GSettings schema file for their preferences, named
- after the app ([][Overall architecture]).
+ after the app ( [Overall architecture]( {{< ref "#overall-architecture" >}} )).
- Existing GSettings schemas are re-used where possible for user and
- system settings ([][Existing preferences schemas]).
+ system settings ( [Existing preferences schemas]( {{< ref "#existing-preferences-schemas" >}} )).
- Using the normal GSettings approach for handling app upgrades
- ([][Overall architecture]).
+ ( [Overall architecture]( {{< ref "#overall-architecture" >}} )).
- Developing against the normal dconf backend for GSettings (section
- [][Development backend].
+ [Development backend]( {{< ref "#development-backend" >}} ).
- Switching to the proxied dconf backend once it’s ready, to support
- access control ([][Proxied dconf backend]).
+ access control ( [Proxied dconf backend]( {{< ref "#proxied-dconf-backend" >}} )).
- - A key-file backend is an alternative we do *not* recommend ([][Key-file backend]).
+ - A key-file backend is an alternative we do *not* recommend ( [Key-file backend]( {{< ref "#key-file-backend" >}} )).
- Permissions to modify user or system settings are controlled by the
- app’s manifest ([][Security policy]).
+ app’s manifest ( [Security policy]( {{< ref "#security-policy" >}} )).
- Permissions are converted to backend-specific AppArmor rules by the
- app store ([][Security policy]).
+ app store ( [Security policy]( {{< ref "#security-policy" >}} )).
- User interfaces for preferences are provided by the vendor,
automatically generated from GSettings schemas; or provided by
- applications ([][User interface]).
+ applications ( [User interface]( {{< ref "#user-interface" >}} )).
- Apertis provides a standard widget to present GSettings schemas as a
- preferences UI ([][Preferences list widget]).
+ preferences UI ( [Preferences list widget]( {{< ref "#preferences-list-widget" >}} )).
- Preferences hard key support is added according to the Hard Keys
- design ([](#preferences-hard-key)).
+ design [preferences hard key]( {{< ref "#preferences-hard-key" >}} )).
- - Providing API to get a persistent data storage location ([][Well known state directories]).
+ - Providing API to get a persistent data storage location ( [Well known state directories]( {{< ref "#well-known-state-directories" >}} )).
- - Persistent data is private to each (user, app) pair ([][Well known state directories]).
+ - Persistent data is private to each (user, app) pair ( [Well known state directories]( {{< ref "#well-known-state-directories" >}} )).
- Recommending various different data storage APIs to suit different
- apps’ use cases ([][Recommended serialisation APIs]).
+ apps’ use cases ( [Recommended serialisation APIs]( {{< ref "#recommended-serialisation-apis" >}} )).
- Apps explicitly define which data will persist, and are responsible
- for saving it and migrating it from older to newer versions ([][Overall architecture]).
+ for saving it and migrating it from older to newer versions ( [Overall architecture]( {{< ref "#overall-architecture" >}} )).
- Apps can be instructed to save their persistent state by the
- operating system via a D-Bus interface ([][When to save persistent data]).
+ operating system via a D-Bus interface ( [When to save persistent data]( {{< ref "#when-to-save-persistent-data" >}} )).
- User secrets and passwords are stored using the freedesktop.org
Secrets D-Bus API, not the Apertis preferences or persistence APIs
- ([][Approach]).
+ ( [Approach]( {{< ref "#approach" >}} )).
[GSettings]: https://developer.gnome.org/gio/stable/GSettings.html#GSettings.description
diff --git a/content/designs/release-flow.md b/content/designs/release-flow.md
index a776f2b33b6c1dfb38972e6aca7deac29dbd780d..50acb4afc1482caf9e7446dc1f807c76a4643812 100644
--- a/content/designs/release-flow.md
+++ b/content/designs/release-flow.md
@@ -319,7 +319,7 @@ For each quarter the releases would be (with some examples):
The following diagram shows how this would look for Apertis releases up to
2023:
-
+
Further details about the various types of release will be given in the
following sections.
diff --git a/content/designs/robustness.md b/content/designs/robustness.md
index 83ceda3c0fa2bb10f9023939a85872b443567403..a3aaa5becdfdfefb5eb8aad583fda6be32e4fd6b 100644
--- a/content/designs/robustness.md
+++ b/content/designs/robustness.md
@@ -133,7 +133,7 @@ files in the /home filesystem and in attached removable devices.
If the Tracker database that contains the meta-data has been corrupted,
it should be moved to the side (or deleted) and recreated again by
indexing all available media files. To minimize the chances of
-corruption, refer to [][Tracker].
+corruption, refer to [Tracker]( {{< ref "#tracker" >}} ).
Software that reads the actual media files should assume media files may
contain invalid data and ignore them without further loss of
@@ -178,7 +178,7 @@ mode, but at a large cost to performance.
Btrfs has been created on very robust principles, building upon the
experience of Ext4. Some brief technical details are provided at the end
-of this document in [][BTRFS overview].
+of this document in [BTRFS overview]( {{< ref "#btrfs-overview" >}} ).
##### Filesystem options
@@ -221,7 +221,7 @@ hardware features available with the storage media.
- Recovery (default: off)
This option can be used to attempt recovery of a corrupted
- filesystem (See [][Repair and recovery]).
+ filesystem (See [Repair and recovery]( {{< ref "#repair-and-recovery" >}} )).
- *Filesystem creation options:*
@@ -258,7 +258,7 @@ the FAT32 and BTRFS filesystems are used. The partitions are configured
the “sync†and “flush†flags.
- **System** - Since BTRFS provides an excellent snapshot mechanism to
- assist system rollbacks (See [][Cheap, fast, and atomic snapshots and rollback]),
+ assist system rollbacks (See [Cheap, fast, and atomic snapshots and rollback]( {{< ref "#cheap-fast-and-atomic-snapshots-and-rollback" >}} )),
this partition will be populated with a
BTRFS filesystem created with the appropriate sector size for the
storage device. It may be created with mixed block groups to save
@@ -302,7 +302,7 @@ corruption is beyond the scope of this feature.
checksummed. This is the default behaviour and the current checksum
algorithm uses few resources. This method of checksumming can detect
all the ways in which corruption can occur to data on the
- filesystem. See [][Checksumming] for more detail.
+ filesystem. See [Checksumming]( {{< ref "#checksumming" >}} ) for more detail.
- **Ext4** maintains checksums for journal data only, no checksumming
of file data takes place.
@@ -415,7 +415,7 @@ commands, or data will be lost. Applications that write to removable
drives must be robust enough to be able to continue in the face of such
errors with minimal loss of functionality.
-As mentioned in [][Filesystems], the safest way to use
+As mentioned in [Filesystems]( {{< ref "#filesystems" >}} ), the safest way to use
removable drives is by restricting the processes that can write to the
drive, and minimizing the time-window for the writes. For that to be
practical, there should be a system service that is the only one allowed
@@ -425,7 +425,7 @@ then remount read-only again.
Since, for interoperability reasons, the filesystem used in removable
devices is FAT32, in addition to the issues mentioned in this section,
-the robustness considerations that were explained earlier in [][Filesystems]
+the robustness considerations that were explained earlier in [Filesystems]( {{< ref "#filesystems" >}} )
also apply.
### Mitigating the effects of lack of disk space
diff --git a/content/designs/secure-boot.md b/content/designs/secure-boot.md
index 0a920d17a0f9ff9192018f3850838b919e635782..6139e583b326f847c3c59952fe1084d3d91161a0 100644
--- a/content/designs/secure-boot.md
+++ b/content/designs/secure-boot.md
@@ -591,7 +591,7 @@ available only on several steps. Hence we add "private" keys and password
file as "Secret file" global credentials to demonstrate the integration
into the Jenkins pipeline:
-
+
For keys usage they should be available during the call of `cst` tool,
so we have to add into the Jenkins pipeline copying of these secret files
diff --git a/content/designs/security.md b/content/designs/security.md
index 30abc937709eab7da4681d644ad6ca348b918c4a..92f95124f102a481db3a5ba1c128ef2d7c72c664 100644
--- a/content/designs/security.md
+++ b/content/designs/security.md
@@ -13,13 +13,13 @@ outputs = [ "html", "pdf-in",]
This document discusses and details solutions for the security
requirements of the Apertis system.
-[][Security boundaries and threat model] describes the various
+ [Security boundaries and threat model]( {{< ref "#security-boundaries-and-threat-model" >}} ) describes the various
aspects of the security model, and the threat model for each.
Local attacks to obtain private data or damage the system, including
those performed by malicious applications that get installed in the
device somehow or through exploiting a vulnerable application are
-covered in [][Mandatory access control] (MAC). It is also the
+covered in [Mandatory access control]( {{< ref "#mandatory-access-control" >}} ) (MAC). It is also the
main line of defense against malicious email attachments and web
content, and for minimizing the damage that root is able to do are also
mainly covered by the MAC infrastructure. This is the main security
@@ -27,32 +27,32 @@ infrastructure of the system, and the depth of the discussion is
proportional to its importance.
Denial of Service attacks through abuse of system resources such as CPU
-and memory are covered by [][Resource usage control]. Attacks
+and memory are covered by [Resource usage control]( {{< ref "#resource-usage-control" >}} ). Attacks
coming in through the device's network connections and possible
-strategies for firewall setup are covered in [][Network filtering]
+strategies for firewall setup are covered in [Network filtering]( {{< ref "#network-filtering" >}} )
Attacks to the driver assistance system coming from the infotainment
system are handled by many of these security components, so it is
-discussed in a separate section: [][Protecting the driver assistance system from attacks].
+discussed in a separate section: [Protecting the driver assistance system from attacks]( {{< ref "#protecting-the-driver-assistance-system-from-attacks" >}} ).
Internet threats are the main subject of 10,
-[][Protecting the system from internet threats].
+ [Protecting the system from internet threats]( {{< ref "#protecting-the-system-from-internet-threats" >}} ).
-[][Secure software distribution] discusses how to provide ways
+ [Secure software distribution]( {{< ref "#secure-software-distribution" >}} ) discusses how to provide ways
to make installing and upgrade software secure, by guaranteeing packages
are unchanged, undamaged and coming from a trusted repository.
Secure boot for protecting the system against attacks done by having
-physical access to the device is discussed in [][Secure boot].
-[][Data encryption and removal], is concerned with features
+physical access to the device is discussed in [Secure boot]( {{< ref "#secure-boot" >}} ).
+ [Data encryption and removal]( {{< ref "#data-encryption-and-removal" >}} ), is concerned with features
whose main focus is to protect the privacy of the user.
-[][Stack protection], discusses simple but effective techniques
+ [Stack protection]( {{< ref "#stack-protection" >}} ), discusses simple but effective techniques
that can be used to harden applications and prevent exploitation of
-vulnerabilities. [][Confining applications in containers],
+vulnerabilities. [Confining applications in containers]( {{< ref "#confining-applications-in-containers" >}} ),
discusses the pros and cons of using the lightweight Linux Containers
infrastructure for a system like Apertis.
-[][The IMA Linux integrity subsystem], wraps up this document by
+ [The IMA Linux integrity subsystem]( {{< ref "#the-ima-linux-integrity-subsystem" >}} ), wraps up this document by
discussing how the Integrity Measurement Architecture works and what
features it brings to the table, and at what cost.
@@ -180,7 +180,7 @@ using questions similar to these:
privilege flag, specific applications, or some combination of those?
It is also necessary to consider whether data stored by different users
-using the same application must be separated (see [][Security between users]).
+using the same application must be separated (see [Security between users]( {{< ref "#security-between-users" >}} )).
For example, a platform service for downloads might have the policy that
each application's download history can be read by the matching
@@ -253,7 +253,7 @@ Some platform components, notably the Linux kernel, are sufficiently
highly-privileged that it does not make sense to attempt to restrict
them, because carrying out their normal functionality requires
sufficiently broad access that they can violate one of the layers of the
-security model. As noted in [][Terminology], these components are
+security model. As noted in [Terminology]( {{< ref "#terminology" >}} ), these components are
said to be part of the *trusted computing base* for that layer; the
number and size of these components should be minimized, to reduce the
exposure of the system as a whole.
@@ -345,18 +345,18 @@ Android re-purposed the concept of UNIX user ID (uid), making each
application run as a different user ID. This allows for very tight
control over what files each application is able to access by simply
using user-based permissions; this provides isolation between
-applications ([][Security between applications]). In later Android versions, which do have
+applications ( [Security between applications]( {{< ref "#security-between-applications" >}} )). In later Android versions, which do have
multi-user support, user IDs are used to provide two separate security
boundaries – isolating applications from each other, and isolating users
-from each other ([][Security between users]) – with one user ID per (user, app) pair.
+from each other ( [Security between users]( {{< ref "#security-between-users" >}} )) – with one user ID per (user, app) pair.
This is discussed in more detail in the [Multiuser design document](multiuser.md).
The system's main file system is mounted read-only to protect against
unauthorized tampering with system files (integrity for platform data,
-[][Security between platform services]); however, this does not protect integrity against an
-attacker with physical access ([][Physical security]). Encryption of the user data
+ [Security between platform services]( {{< ref "#security-between-platform-services" >}} )); however, this does not protect integrity against an
+attacker with physical access ( [Physical security]( {{< ref "#physical-security" >}} )). Encryption of the user data
partition through the standard *dm-crypt* kernel facility
-(confidentiality despite physical access, [][Physical security]) is supported if the user
+(confidentiality despite physical access, [Physical security]( {{< ref "#physical-security" >}} )) is supported if the user
configures a password for their device. Users using gesture-based or
other unlock mechanisms are unable to use this feature.
@@ -487,10 +487,10 @@ step.
## Mandatory Access Control
The goal of the Linux Discretionary Access Control (DAC) is a separation
-of multiple users and their data ([][Security between users],
-[][Security between platform services]). The policies are
+of multiple users and their data ( [Security between users]( {{< ref "#security-between-users" >}} ),
+ [Security between platform services]( {{< ref "#security-between-platform-services" >}} )). The policies are
based on the identity of a subject or their groups. Since in Apertis
-applications from the same user should not trust each other ([][Security between applications]),
+applications from the same user should not trust each other ( [Security between applications]( {{< ref "#security-between-applications" >}} )),
the utilization of a Mandatory Access Control (MAC) system is
recommended. MAC is implemented in Linux by one of the available Linux
Security Modules (LSM).
@@ -751,7 +751,7 @@ only checks whether a given client can talk to a given service.
One caveat regarding fine-grained (interface- and path-based) D-Bus
access control is that it is often not directly useful, since the
interface and path is not necessarily sufficient to determine whether an
-action should be allowed or denied (for example, [][Motivation for polkit] describes
+action should be allowed or denied (for example, [Motivation for polkit]( {{< ref "#motivation-for-polkit" >}} ) describes
why this is the case for the udisks service). As a result of
considerations like this, the developers of kdbus oppose the
addition of fine-grained access control within kdbus, and have indicated
@@ -962,13 +962,13 @@ convenient to test and debug issues.
Note, also, that writing to the **/etc/apparmor.d/disable** directory is
required for creating the symlink there, and the UNIX DAC permissions
system already protects that directory for writing - only root is able
-to write to this directory. As discussed in [][A note about root], if an
+to write to this directory. As discussed in [A note about root]( {{< ref "#a-note-about-root" >}} ), if an
attacker becomes root the system is already compromised.
Also, as discussed in the System update & rollback, the system partition
will be mounted read-only, so that is an additional protection layer
already. And in addition to that, the white-list approach discussed in
-[][Implementing a white list approach] will already deny writing to anywhere in the file system,
+ [Implementing a white list approach]( {{< ref "#implementing-a-white-list-approach" >}} ) will already deny writing to anywhere in the file system,
so anything running under the application manager will have an
additional layer of security imposed on them.
@@ -1004,7 +1004,7 @@ one or a few services should be installed in a private location, such as
the application's directory. That would put those libraries outside of
the paths covered by the existing rules, and they would this be out of
reach for any other application already, given the white-list approach
-to session lockdown, as discussed in [][Implementing a white list approach].
+to session lockdown, as discussed in [Implementing a white list approach]( {{< ref "#implementing-a-white-list-approach" >}} ).
If that is not possible, because the library hardcodes paths or some
other issue, an explicit deny rule could be added to the
@@ -1564,7 +1564,7 @@ least privileges when it comes to interfacing with the system, so the
AppArmor policies that apply to it can be very strict. If a limited set
of plugins is supported, the same can be applied to the Plugin processes.
In fact, the WebKit codebase contains support for using seccomp filters
-(see [][Seccomp]) to sandbox the WebKit2 processes. It may be a useful
+(see [Seccomp]( {{< ref "#seccomp" >}} )) to sandbox the WebKit2 processes. It may be a useful
addition in the future.
### Other sources of potential exploitation
@@ -1582,7 +1582,7 @@ exploited to cause denial of service or run arbitrary code.
Although these cases do deserve mention specifically for the inherent
risk they bring, there is no silver bullet for this problem. Keeping
applications up-to-date with security fixes, using hardening techniques
-such as stack protection, discussed in [][Stack protection], and locking the
+such as stack protection, discussed in [Stack protection]( {{< ref "#stack-protection" >}} ), and locking the
application down to its minimum access requirements are the tools that
can be employed to reduce the risks.
@@ -1667,7 +1667,7 @@ system snapshots and rolling back updates.
More discussion of system integrity checking, its limitations and
alternatives can be found later on, when the IMA system is investigated.
-See [][Conclusion regarding IMA and EVM] in particular.
+See [Conclusion regarding IMA and EVM]( {{< ref "#conclusion-regarding-ima-and-evm" >}} ) in particular.
The signature and verification processes are described in the Freescale
white paper “Security Features of the i.MX31 and i.MX31Lâ€.
@@ -1813,7 +1813,7 @@ indirection.
[Flatpak] is a framework for “sandboxed†desktop applications, under
development by several GNOME developers. Like LXC, it makes use of
-existing Linux infrastructure such as cgroups (see [][Resource usage control]) and
+existing Linux infrastructure such as cgroups (see [Resource usage control]( {{< ref "#resource-usage-control" >}} )) and
namespaces.
Unlike LXC, Flatpak's design goals are focused on confining individual
@@ -1900,7 +1900,7 @@ breaches, protecting the base system and validating the authenticity of
system files are attained in much better ways through other means, such
as keeping the system files separate and read-only during normal
operation, and using secure methods for installing and updating
-software, such as those described in [][Protecting the driver assistance system from attacks].
+software, such as those described in [Protecting the driver assistance system from attacks]( {{< ref "#protecting-the-driver-assistance-system-from-attacks" >}} ).
For these reasons Collabora advises against the usage of IMA and EVM for
this project. An option to provide some security for the system in this
@@ -2027,12 +2027,12 @@ The *install to target* functionality that was made available through an
Eclipse plugin uses an **sftp** connection with an arbitrary user and
password pair to connect to the device. This means that putting the
device in developer mode should ensure the **ssh** server is running and
-add an exception to the firewall rules discussed in [][Network filtering],
+add an exception to the firewall rules discussed in [Network filtering]( {{< ref "#network-filtering" >}} ),
to allow an inbound connection to port 22.
Upon login, the SSH server will start user sessions that are not
constrained by the AppArmor infrastructure. In particular the white-list
-policy discussed in section [][Implementing a white list approach],
+policy discussed in section [Implementing a white list approach]( {{< ref "#implementing-a-white-list-approach" >}} ),
will not apply to ssh user sessions. This means the user the IDE will
connect with needs file system access to the directory where the
application needs to be installed or be able to tell the application
@@ -2064,13 +2064,13 @@ discussion, or a more detailed design. These may be better written as
Wiki pages rather than formal designs, given they require and benefit
from iterating on an implementation.
- - Define which cgroups ([][Resource usage control]) to have, how they will be created
+ - Define which cgroups ( [Resource usage control]( {{< ref "#resource-usage-control" >}} )) to have, how they will be created
and managed
- - Define exactly what Netfilter rules ([][Network filtering]) should be installed
+ - Define exactly what Netfilter rules ( [Network filtering]( {{< ref "#network-filtering" >}} )) should be installed
and how they will be made effective at boot time
- - Evaluate Flatpak ([][The Flatpak framework])
+ - Evaluate Flatpak ( [The Flatpak framework]( {{< ref "#the-flatpak-framework" >}} ))
[Interface Discovery]: https://wiki.apertis.org/Interface_discovery
diff --git a/content/designs/sensors-and-actuators.md b/content/designs/sensors-and-actuators.md
index 506e30f0d6949995bc42ad9929e8986ec73bce28..7fb629af79c29fa8a006d4c83a70fc61a6fc906c 100644
--- a/content/designs/sensors-and-actuators.md
+++ b/content/designs/sensors-and-actuators.md
@@ -234,7 +234,7 @@ manufacturer does not expect their bundle to be used in other vehicles.
An application bundle which connects to wrist watch body monitors on
each of the passengers (through an out-of-band channel like Bluetooth,
-which is out of the scope of this document; see [][Bluetooth wrist watch and the Internet of Things]
+which is out of the scope of this document; see [Bluetooth wrist watch and the Internet of Things]( {{< ref "#bluetooth-wrist-watch-and-the-internet-of-things" >}} )
may want to change the cabin temperature in
response to thermometer readings from passengers’ watches.
@@ -348,7 +348,7 @@ use-case-by-use-case basis, using separate system components to those
handling intra-vehicle sensors and actuators. This ensures that control
over actuators, which is safety critical, remains in a separate security
domain from C2C and C2X, which must not have access to actuators on the
-local vehicle. See [][Security].
+local vehicle. See [Security]( {{< ref "#security" >}} ).
An initial suggestion for C2C and C2X communications would be to
implement them as a separate service which consumes sensor data from the
@@ -372,11 +372,11 @@ journey.
An application bundle must be able to enumerate devices in the vehicle,
including information about where they are located in the vehicle (for
example, so that it can adjust the position and setup of the driver’s
-seat but not others (see [][Driving setup bundle])).
+seat but not others (see [Driving setup bundle]( {{< ref "#driving-setup-bundle" >}} ))).
It is expected that the set of devices in a vehicle may change
dynamically while the vehicle is running, for example if a roof box were
-added while the engine was running ([][Roof box]).
+added while the engine was running ( [Roof box]( {{< ref "#roof-box" >}} )).
Enumeration is particularly important for bundles, as the set of sensors
in a particular vehicle will not change, but the set of sensors seen by
@@ -387,7 +387,7 @@ significantly.
An application bundle must be able to enumerate vehicles connected to
the inter-vehicle network, for example to discover the existence of
-hitched trailers or agricultural vehicles ([][Trailer], [][Agricultural vehicle]).
+hitched trailers or agricultural vehicles ( [Trailer]( {{< ref "#trailer" >}} ), [Agricultural vehicle]( {{< ref "#agricultural-vehicle" >}} )).
It is expected that the set of vehicles may change dynamically while the
vehicles are running.
@@ -398,7 +398,7 @@ An application bundle must be able to retrieve data from sensors. This
data must be strongly typed in order to minimise the possibility of a
bundle misinterpreting it, or sensors from different manufacturers using
different units, for example. Sensor data could vary in type from
-booleans (see [][Night mode]) through to streaming video data (see [][Augmented reality parking]).
+booleans (see [Night mode]( {{< ref "#night-mode" >}} )) through to streaming video data (see [Augmented reality parking]( {{< ref "#augmented-reality-parking" >}} )).
Sensor data may be processed by the system to make it
more useful for application bundles; they do not need direct access to
raw sensor data.
@@ -410,14 +410,14 @@ invoking methods on them). This data must be strongly typed in order to
minimise the possibility of a bundle misinterpreting it, or actuators
from different manufacturers using different units, for example.
Actuator data could vary in type from booleans through to enumerated
-types (see [][Driving setup bundle]) and possibly larger data streams,
+types (see [Driving setup bundle]( {{< ref "#driving-setup-bundle" >}} )) and possibly larger data streams,
though no concrete use cases exist for that.
### Network independence
The API should be independent of the network used to connect to devices
— whether it be Ethernet, LIN or CAN; or whether the device is
-connected directly to a host processor ([][Ethernet intra-vehicle network]).
+connected directly to a host processor ( [Ethernet intra-vehicle network]( {{< ref "#ethernet-intra-vehicle-network" >}} )).
### Bounded latency of processing sensor data
@@ -428,8 +428,8 @@ sensor readings are missed, accuracy decreases. Sensor readings should
be processed within the latency limits specified by the sensors. The
limits on forwarding this processed data to bundles are less strict,
though it is expected to be within the latency noticeable by humans
-(around 20ms) so that it can be displayed in real time (see [][Augmented reality parking],
-[][Sightseeing application bundle], [][Changing audio volume with vehicle or cabin noise]).
+(around 20ms) so that it can be displayed in real time (see [Augmented reality parking]( {{< ref "#augmented-reality-parking" >}} ),
+ [Sightseeing application bundle]( {{< ref "#sightseeing-application-bundle" >}} ), [Changing audio volume with vehicle or cabin noise]( {{< ref "#changing-audio-volume-with-vehicle-or-cabin-noise" >}} )).
### Extensibility for OEMs
@@ -441,7 +441,7 @@ parties working with them to define new device types when developing a
new vehicle or an installation or accessory to go with it. In order for
new devices to be usable by non-OEM application bundle authors, the
Sensors and Actuators API must be updatable or extensible to support
-them. ([][Odour detection], [][Truck installations].)
+them. ( [Odour detection]( {{< ref "#odour-detection" >}} ), [Truck installations]( {{< ref "#truck-installations" >}} ).)
### Third-party backends
@@ -451,7 +451,7 @@ between the device and the Apertis sensors and actuators service. This
code must be written by the device manufacturer, as they know the
hardware, and must be installable on the Apertis system before or after
vehicle production (so as a system or non-system application). (See
-[][Agricultural vehicle], [][Roof box], [][Truck installations].)
+ [Agricultural vehicle]( {{< ref "#agricultural-vehicle" >}} ), [Roof box]( {{< ref "#roof-box" >}} ), [Truck installations]( {{< ref "#truck-installations" >}} ).)
### Third-party backend validation
@@ -460,20 +460,20 @@ the third party might not be one who has contributed to or used Apertis
before. There must be a process for validating backends for the sensors
and actuators system, to ensure they have a certain level of code
quality and security, in order to reduce the attack surface of the
-service as a whole. (See [][Roof box].)
+service as a whole. (See [Roof box]( {{< ref "#roof-box" >}} ).)
### Notifications of changes to sensor data
All sensor data changes over time, so the API must support notifying
application bundles of changes to sensor data they are interested in,
-without requiring the bundle to poll for updates (see [][Petrol station finder],
-[][Sightseeing application bundle], [][Changing bundle functionality when driving at speed],
-[][Changing audio volume with vehicle or cabin noise], [][Night mode],
-[][Odour detection]).
+without requiring the bundle to poll for updates (see [Petrol station finder]( {{< ref "#petrol-station-finder" >}} ),
+ [Sightseeing application bundle]( {{< ref "#sightseeing-application-bundle" >}} ), [Changing bundle functionality when driving at speed]( {{< ref "#changing-bundle-functionality-when-driving-at-speed" >}} ),
+ [Changing audio volume with vehicle or cabin noise]( {{< ref "#changing-audio-volume-with-vehicle-or-cabin-noise" >}} ), [Night mode]( {{< ref "#night-mode" >}} ),
+ [Odour detection]( {{< ref "#odour-detection" >}} )).
Application bundles should be able to request notifications only when a
sensor value crosses a given threshold, to avoid unnecessary
-notifications (see [][Changing bundle functionality when driving at speed]).
+notifications (see [Changing bundle functionality when driving at speed]( {{< ref "#changing-bundle-functionality-when-driving-at-speed" >}} )).
### Uncertainty bounds
@@ -484,7 +484,7 @@ phone tower varies with your location.
This is especially possible with data aggregated from multiple sensors,
where the aggregate accuracy can be statistically modelled (for example,
-distance calculation from multiple sensors in [][Weather feedback or traffic jam feedback]).
+distance calculation from multiple sensors in [Weather feedback or traffic jam feedback]( {{< ref "#weather-feedback-or-traffic-jam-feedback" >}} )).
### Failure feedback
@@ -496,9 +496,9 @@ For example, the air conditioning coolant on an older vehicle might have
leaked, leaving the air conditioning system unable to cool the cabin
effectively. Application bundles which wish to set the temperature need
to have feedback from a thermometer to work out whether the temperature
-has reached the target value (see [][Air conditioning control]).
+has reached the target value (see [Air conditioning control]( {{< ref "#air-conditioning-control" >}} )).
-Another example is failure to close windows: [][Automatic window feedback].
+Another example is failure to close windows: [Automatic window feedback]( {{< ref "#automatic-window-feedback" >}} ).
### Timestamping
@@ -506,14 +506,14 @@ In-vehicle networks (especially Ethernet) may have variable latency. In
order to correlate measurements from multiple sensors on the end of
connections of varying latency, each measurement should have an
associated timestamp, added at the time the measurement was recorded
-(see [][Augmented reality parking], [][Sightseeing application bundle]).
+(see [Augmented reality parking]( {{< ref "#augmented-reality-parking" >}} ), [Sightseeing application bundle]( {{< ref "#sightseeing-application-bundle" >}} )).
### Triggering bundle activation
Various use cases require a bundle to be able to trigger actions based
on sensor data reaching a certain value, even if the program is not
-running at that time (see [][Petrol station finder],
-[][Changing audio volume with vehicle or cabin noise], [][Odour detection]).
+running at that time (see [Petrol station finder]( {{< ref "#petrol-station-finder" >}} ),
+ [Changing audio volume with vehicle or cabin noise]( {{< ref "#changing-audio-volume-with-vehicle-or-cabin-noise" >}} ), [Odour detection]( {{< ref "#odour-detection" >}} )).
This requires some
operating system service to monitor a list of trigger conditions even
while the programs which set those triggers are not running, and start
@@ -523,8 +523,8 @@ the appropriate program so that it can respond to that trigger.
Some bundles require to be able to regularly record sensor measurements,
with the intention of processing them (for example, uploading them to an
-online service) at a later time (see [][Weather feedback or traffic jam feedback],
-[][Insurance bundle]). This is not latency sensitive. As an
+online service) at a later time (see [Weather feedback or traffic jam feedback]( {{< ref "#weather-feedback-or-traffic-jam-feedback" >}} ),
+ [Insurance bundle]( {{< ref "#insurance-bundle" >}} )). This is not latency sensitive. As an
optimisation, a system service could record the sensor readings for
them, to avoid waking up the programs regularly.
@@ -538,13 +538,13 @@ periodically overwrite recorded data if running low on space.
### Sensor security
As highlighted by the privacy concerns in several of the use cases
-([][Sightseeing application bundle], [][Changing audio volume with vehicle or cabin noise],
-[][Insurance bundle]), there are security concerns with
+( [Sightseeing application bundle]( {{< ref "#sightseeing-application-bundle" >}} ), [Changing audio volume with vehicle or cabin noise]( {{< ref "#changing-audio-volume-with-vehicle-or-cabin-noise" >}} ),
+ [Insurance bundle]( {{< ref "#insurance-bundle" >}} )), there are security concerns with
allowing bundles access to sensor data. The system must be able to
restrict access to some or all types of sensor data unless the user has
explicitly granted a bundle access to it. Bundles with access to sensor
data must be in separate security domains to prevent privilege
-escalation ([][Compromised application bundle]).
+escalation ( [Compromised application bundle]( {{< ref "#compromised-application-bundle" >}} )).
### Actuator security
@@ -552,38 +552,38 @@ Control of actuators is safety critical but not privacy sensitive
(unlike sensors). The system must be able to restrict write access to
some or all types of actuator unless the user has explicitly granted a
bundle access to it. Bundles with access to actuators must be in
-separate security domains to prevent privilege escalation ([][Compromised application bundle]).
+separate security domains to prevent privilege escalation ( [Compromised application bundle]( {{< ref "#compromised-application-bundle" >}} )).
### App store knowledge of device requirements
The Apertis store must know which devices (sensors *and* actuators) an
application bundle requires to function, and should not allow the user
to install a bundle which requires a device their vehicle does not have,
-or the bundle would be useless ([][Basic model vehicle]).
+or the bundle would be useless ( [Basic model vehicle]( {{< ref "#basic-model-vehicle" >}} )).
### Accessing devices on multiple vehicles
The API must support accessing properties for multiple vehicles, such as
-hitched agricultural trailers ([][Agricultural vehicle]) or car trailers
-([][Trailer]). These vehicles may appear dynamically while the IVI system is
+hitched agricultural trailers ( [Agricultural vehicle]( {{< ref "#agricultural-vehicle" >}} )) or car trailers
+( [Trailer]( {{< ref "#trailer" >}} )). These vehicles may appear dynamically while the IVI system is
running; for example, in the case where the driver hitches a trailer
with the engine running.
**Note**: This requirement explicitly does not support C2C or C2X, which
-are out of scope of this document. (See [][Car-to-car and car-to-infrastructure communications]).
+are out of scope of this document. (See [Car-to-car and car-to-infrastructure communications]( {{< ref "#car-to-car-and-car-to-infrastructure-communications" >}} )).
### Third-party accessories
The API must support accessing properties of third-party accessories —
-either dynamically attached to the vehicle ([][Roof box]) or installed
-during manufacture ([][Truck installations]).
+either dynamically attached to the vehicle ( [Roof box]( {{< ref "#roof-box" >}} )) or installed
+during manufacture ( [Truck installations]( {{< ref "#truck-installations" >}} )).
### SDK hardware support
The SDK must contain a backend for the system which allows appropriate
hardware which is attached to the developer’s machine to be used as
sensors or actuators for development and testing of applications (see
-[][Development against the SDK]).
+ [Development against the SDK]( {{< ref "#development-against-the-sdk" >}} )).
This backend must not be available in target images.
@@ -821,7 +821,7 @@ is written in C++, it uses GNOME technologies like GObject
Introspection; but it also uses Qt. Its main daemon is the Automotive
Message Broker daemon, ambd.
-One area where it differs from the Apertis design is [][Security];
+One area where it differs from the Apertis design is [Security]( {{< ref "#security" >}} );
it does not implement the polkit integration which is key to
the vehicle device daemon security domain boundary. Modifying the
security architecture of a large software project after its initial
@@ -838,7 +838,7 @@ The [AllJoyn Framework] is an internet of things (IoT) framework
produced under the Linux Foundation banner and the [AllSeen
Alliance]. (Note that IoT frameworks are explicitly out of scope
for this design; this section is for background information only. See
-[][Bluetooth wrist watch and the Internet of Things]) It allows devices to discover and communicate with each
+ [Bluetooth wrist watch and the Internet of Things]( {{< ref "#bluetooth-wrist-watch-and-the-internet-of-things" >}} )) It allows devices to discover and communicate with each
other. It is freely available (open source) and has components which run
on various different operating systems.
@@ -863,24 +863,24 @@ application uses the lamp service API which abstracts over these.
## Approach
-Based on the above research ([][Existing sensor systems]) and [][Requirements], we
+Based on the above research ( [Existing sensor systems]( {{< ref "#existing-sensor-systems" >}} )) and [Requirements]( {{< ref "#requirements" >}} ), we
recommend the following approach as an initial sketch of a Sensors and
Actuators API.
### Overall architecture
-
+
### Vehicle device daemon
Implement a vehicle device daemon which aggregates all sensor data in
the vehicle, and multiplexes access to all actuators in the vehicle
-(apart from specialised high bandwidth devices; see [][High bandwidth or low latency sensors]).
+(apart from specialised high bandwidth devices; see [High bandwidth or low latency sensors]( {{< ref "#high-bandwidth-or-low-latency-sensors" >}} )).
It will connect to whichever underlying buses are
used by the OEM to connect devices (for example, the CAN and LIN buses);
-see [][Hardware and app APIs]. The implementation may be new, or may be a
+see [Hardware and app APIs]( {{< ref "#hardware-and-app-apis" >}} ). The implementation may be new, or may be a
modified version of ambd, although it would need large amounts of rework
-to fit the Apertis design (see [][Automotive message broker]).
+to fit the Apertis design (see [Automotive message broker]( {{< ref "#automotive-message-broker" >}} )).
The daemon needs to receive and process input within the latency bounds
of the sensors.
@@ -910,7 +910,7 @@ available for all applications to use. If a vehicle needs to be released
with those sensors or actuators in the meantime, their properties must
be added to the SDK API in an OEM-specific namespace. Applications from
the OEM can use properties from this namespace until they are
-standardised in Apertis. See [][Property naming].
+standardised in Apertis. See [Property naming]( {{< ref "#property-naming" >}} ).
Multiple vehicles can be supported by exposing new top-level instances
of the [Vehicle interface][w3-vehicle-interface]. For example, each vehicle could be
@@ -979,13 +979,13 @@ hardware API needs the following functionality:
The hardware API will be roughly a similar shape to the SDK API, and
hence a lot of complexity of the vehicle device daemon will be in the
-vehicle-specific backends (both operate on properties — [][Properties vs devices]).
+vehicle-specific backends (both operate on properties — [Properties vs devices]( {{< ref "#properties-vs-devices" >}} )).
As vehicle networks differ, the backend used in a given vehicle has to
be developed by the OEM developing that vehicle. Apertis may be able to
provide some common utility functions to help in implementing backends,
but cannot abstract all the differences between vehicles. (See
-[][Background on intra-vehicle networks]).
+ [Background on intra-vehicle networks]( {{< ref "#background-on-intra-vehicle-networks" >}} )).
It is expected that the main backend service for a vehicle, provided by
that vehicle’s OEM, will be access the vehicle-specific network
@@ -1001,7 +1001,7 @@ The path for a property to pass from a hardware sensor through to an
application is long: from the hardware sensor, to the backend service,
through the D-Bus daemon to the vehicle device daemon, then through the
D-Bus daemon again to the application. This is at least 5 IPC hops,
-which could introduce non-negligible latency. See [][High bandwidth or low latency sensors] for
+which could introduce non-negligible latency. See [High bandwidth or low latency sensors]( {{< ref "#high-bandwidth-or-low-latency-sensors" >}} ) for
discussion about this.
#### Interactions between backend services
@@ -1153,12 +1153,12 @@ pass before being deployed in a vehicle.
If a backend service is provided by an application bundle, that
application bundle must additionally undergo more stringent app store
validation, potentially including a requirement for security review of
-its code. See [][Checks for backend services].
+its code. See [Checks for backend services]( {{< ref "#checks-for-backend-services" >}} ).
The compliance test suite must be automated, and should include a
variety of tests to ensure that the hardware API is used correctly by
the backend service. It should be implemented as a mock D-Bus service
-which mocks up the hardware management API ([][Recommended hardware API design]), and which
+which mocks up the hardware management API ( [Recommended hardware API design]( {{< ref "#recommended-hardware-api-design" >}} )), and which
calls the hardware property API. The backend service
must be run against this mock service, and call its methods as normal.
The mock service should return each of the possible return values for
@@ -1197,7 +1197,7 @@ multiple vehicles and third-party accessories; otherwise bundles will
likely never be tested in such configurations. Similarly, it must
support varying properties over time, simulating dynamic addition and
removal of vehicles and devices, and simulating errors in controlling
-actuators (for example, [][Automatic window feedback]).
+actuators (for example, [Automatic window feedback]( {{< ref "#automatic-window-feedback" >}} )).
The emulator should be implemented as a special backend service for the
vehicle device daemon, which is provided by the emulator application.
@@ -1206,7 +1206,7 @@ daemon. This backend, and the emulator should only be available on the
SDK, and must never be available on production systems.
Compliance testing of application bundles is harder, but as a general
-principle, any of the [][Apertis store validation] checks
+principle, any of the [Apertis store validation]( {{< ref "#apertis-store-validation" >}} ) checks
which *can* be brought forward so they can be run by the
bundle developers, *should* be brought forward.
@@ -1219,7 +1219,7 @@ that hardware to applications for development and testing, just as if it
were real hardware in a vehicle.
This backend service must be separate from the emulator backend service
-([][SDK API compliance testing and simulation]), in order to allow them to be used independently.
+( [SDK API compliance testing and simulation]( {{< ref "#sdk-api-compliance-testing-and-simulation" >}} )), in order to allow them to be used independently.
### Trip logging of sensor data
@@ -1348,7 +1348,7 @@ apply to a device are specified as an array of opaque strings, which may
have values other than those in ZonePosition. Multiple strings can be
used (like tags) to describe the location of a device in several
dimensions. Furthermore, zones may be nested hierarchically as discussed
-in [][Recommended hardware API design].
+in [Recommended hardware API design]( {{< ref "#recommended-hardware-api-design" >}} ).
Apertis may extend ZonePosition with additional strings to better
describe device locations. Strings which are not defined in this
@@ -1428,7 +1428,7 @@ bundles which require devices not supported by the user’s vehicle.
From the permissions in the manifest, AppArmor and polkit rules
restricting the program’s access to the vehicle device daemon’s API can
-be generated on installation of the bundle. See [][Security domains] for
+be generated on installation of the bundle. See [Security domains]( {{< ref "#security-domains" >}} ) for
rationale.
When interacting with the vehicle device daemon, a program is securely
@@ -1750,11 +1750,11 @@ application bundle:
be considered to be part of the same security domain as the backend
service, and hence subject to the same validation checks.
- - The backend service must pass the automated compliance test ([][Hardware API compliance testing]).
+ - The backend service must pass the automated compliance test ( [Hardware API compliance testing]( {{< ref "#hardware-api-compliance-testing" >}} )).
- The backend service must not expose any properties which are not
supported by the version of the vehicle device daemon which it
- targets as its minimum dependency (see [][Vehicle device daemon] for information
+ targets as its minimum dependency (see [Vehicle device daemon]( {{< ref "#vehicle-device-daemon" >}} ) for information
about the extension process).
### Suggested roadmap
@@ -1793,111 +1793,111 @@ Initial releases of the system could allow only backend services written
by vehicle OEMs to be used; with later releases allowing third-party
backend services, then ones provided by installed application bundles.
-The emulator backend service ([][SDK API compliance testing and simulation])
+The emulator backend service ( [SDK API compliance testing and simulation]( {{< ref "#sdk-api-compliance-testing-and-simulation" >}} ))
and any SDK hardware backend
-services ([][SDK hardware]) should be implemented early on in development, as
+services ( [SDK hardware]( {{< ref "#sdk-hardware" >}} )) should be implemented early on in development, as
they should be relatively simple, and having them allows application
developers to start writing applications against the service.
### Requirements
- - [][Enumeration of devices]: The availability of known properties of
+ - [Enumeration of devices]( {{< ref "#enumeration-of-devices" >}} ): The availability of known properties of
the vehicle can be checked through the [Availability interface].
The W3C approach considers properties, rather than devices, to be
- the enumerable items, but they are mostly equivalent (see [][Properties vs devices]).
+ the enumerable items, but they are mostly equivalent (see [Properties vs devices]( {{< ref "#properties-vs-devices" >}} )).
- - [][Enumeration of vehicles]: The availability of objects
+ - [Enumeration of vehicles]( {{< ref "#enumeration-of-vehicles" >}} ): The availability of objects
implementing the W3C Vehicle interface on D-Bus is exposed using an
interface like the D-Bus ObjectManager API.
- - [][Retrieving data from sensors]: Properties can be retrieved
+ - [Retrieving data from sensors]( {{< ref "#retrieving-data-from-sensors" >}} ): Properties can be retrieved
through the [VehicleInterface interface][w3-vehicle-interface]. For high bandwidth
sensors, or those with latency requirements for the end-to-end
connection between sensor and bundle, data is transferred out of
- band (see [][High bandwidth or low latency sensors]).
+ band (see [High bandwidth or low latency sensors]( {{< ref "#high-bandwidth-or-low-latency-sensors" >}} )).
- - [][Sending data to actuators]: Properties can be set through the
+ - [Sending data to actuators]( {{< ref "#sending-data-to-actuators" >}} ): Properties can be set through the
[VehicleSignalInterface] interface. As with getting properties,
data for high bandwidth or low latency sensors is transferred out of
band.
- - [][Network independence]: The vehicle device daemon abstracts
+ - [Network independence]( {{< ref "#network-independence" >}} ): The vehicle device daemon abstracts
access to the underlying buses, so bundles are unaware of it.
- - [][Bounded latency of processing sensor data]: The vehicle device
+ - [Bounded latency of processing sensor data]( {{< ref "#bounded-latency-of-processing-sensor-data" >}} ): The vehicle device
daemon should have its scheduling configuration set so that it can
provide latency guarantees for the underlying buses.
- - [][Extensibility for OEMs]: Extensions are standardised through
+ - [Extensibility for OEMs]( {{< ref "#extensibility-for-oems" >}} ): Extensions are standardised through
Apertis and released in the next version of the Sensors and
Actuators API for use by the OEM.
- - [][Third-party backends]: Backend services for the vehicle device
+ - [Third-party backends]( {{< ref "#third-party-backends" >}} ): Backend services for the vehicle device
daemon can be installed as part of application bundles (either
built-in or store bundles).
- - [][Third-party backend validation]: Backend services must be
- validated before being installed as bundles (see [][Checks for backend services]).
+ - [Third-party backend validation]( {{< ref "#third-party-backend-validation" >}} ): Backend services must be
+ validated before being installed as bundles (see [Checks for backend services]( {{< ref "#checks-for-backend-services" >}} )).
- - [][Notifications of changes to sensor data]: Property changes are
+ - [Notifications of changes to sensor data]( {{< ref "#notifications-of-changes-to-sensor-data" >}} ): Property changes are
notified via a publish–subscribe interface on
[VehicleSignalInterface]. Notification thresholds are supported
by optional parameters on that interface.
- - [][Uncertainty bounds]: The W3C API is extended to include
+ - [Uncertainty bounds]( {{< ref "#uncertainty-bounds" >}} ): The W3C API is extended to include
uncertainty bounds for measurements.
- - [][Failure feedback]: Through its use of [Promises], the API
+ - [Failure feedback]( {{< ref "#failure-feedback" >}} ): Through its use of [Promises], the API
allows for failure to set a property.
- - [][Timestamping]: The W3C API is extended to include timestamps
+ - [Timestamping]( {{< ref "#timestamping" >}} ): The W3C API is extended to include timestamps
for measurements.
- - [][Triggering bundle activation]: Programs are woken by
- subscriptions to property changes (see [][Registering triggers and actions]).
+ - [Triggering bundle activation]( {{< ref "#triggering-bundle-activation" >}} ): Programs are woken by
+ subscriptions to property changes (see [Registering triggers and actions]( {{< ref "#registering-triggers-and-actions" >}} )).
- - [][Bulk recording of sensor data]: **Not currently implemented**,
+ - [Bulk recording of sensor data]( {{< ref "#bulk-recording-of-sensor-data" >}} ): **Not currently implemented**,
but may be implemented in future as a straightforward extension to
- the API. See [][Bulk recording of sensor data].
+ the API. See [Bulk recording of sensor data]( {{< ref "#bulk-recording-of-sensor-data" >}} ).
- - [][Sensor security]: Access to the Sensors and Actuators API is
+ - [Sensor security]( {{< ref "#sensor-security" >}} ): Access to the Sensors and Actuators API is
controlled by an AppArmor profile generated from permissions in the
manifest. Access to individual sensors is controlled by a polkit
- rule generated from the same permissions. See [][Security].
+ rule generated from the same permissions. See [Security]( {{< ref "#security" >}} ).
- - [][Actuator security]: As with [][Sensor security]; sensors and actuators are
+ - [Actuator security]( {{< ref "#actuator-security" >}} ): As with [Sensor security]( {{< ref "#sensor-security" >}} ); sensors and actuators are
listed and controlled by the polkit profile separately.
- - [][App-store knowledge of device requirements]: As devices
+ - [App-store knowledge of device requirements]( {{< ref "#app-store-knowledge-of-device-requirements" >}} ): As devices
required by an application bundle are listed in the bundle’s
- manifest (see [][Security]), the Apertis store knows whether the bundle
+ manifest (see [Security]( {{< ref "#security" >}} )), the Apertis store knows whether the bundle
is supported by the user’s vehicle.
- - [][Accessing devices on multiple vehicles]: Each vehicle is
+ - [Accessing devices on multiple vehicles]( {{< ref "#accessing-devices-on-multiple-vehicles" >}} ): Each vehicle is
exposed as a separate D-Bus object, each implementing the W3C
Vehicle interface.
- - [][Third-party accessories]: Properties for third-party
+ - [Third-party accessories]( {{< ref "#third-party-accessories" >}} ): Properties for third-party
accessories must be standardised through Apertis and exposed as
separate interfaces on the vehicle object on D-Bus.
- - [][SDK hardware support]: SDK hardware should be supported through
+ - [SDK hardware support]( {{< ref "#sdk-hardware-support" >}} ): SDK hardware should be supported through
a separate development-only backend service written specifically for
that hardware.
## Open questions
-1. [][Hardware and app APIs]: The exact definition of the SDK API is yet to be finalised. It
+1. [Hardware and app APIs]( {{< ref "#hardware-and-app-apis" >}} ): The exact definition of the SDK API is yet to be finalised. It
should include support for accessing multiple properties in a single
IPC round trip, to reduce IPC overheads.
-2. [][Interactions between backend services]: The exact means for aggregating each property in the Vehicle
+2. [Interactions between backend services]( {{< ref "#interactions-between-backend-services" >}} ): The exact means for aggregating each property in the Vehicle
Data specification is yet to be determined.
-3. [][Zones]: In addition to the current entries in ZonePosition, what other
+3. [Zones]( {{< ref "#zones" >}} ): In addition to the current entries in ZonePosition, what other
zone strings would be useful? ‘internal’ and ‘external’?
-4. [][Security domains]: What is the exact security policy to implement regarding
+4. [Security domains]( {{< ref "#security-domains" >}} ): What is the exact security policy to implement regarding
separation of sensors and actuators? For example, bundle access to
sensors could always be permitted without prompting by returning
polkit.Result.YES for all sensor accesses; but actuator accesses
@@ -1905,7 +1905,7 @@ developers to start writing applications against the service.
polkit.Result.AUTH\_SELF. The choice here depends on the desired
user experience.
-5. [][Apertis store validation]: The specific set of Apertis store validation checks for
+5. [Apertis store validation]( {{< ref "#apertis-store-validation" >}} ): The specific set of Apertis store validation checks for
bundles which access devices is yet to be finalised.
## Summary of recommendations
diff --git a/content/designs/software-development-kit.md b/content/designs/software-development-kit.md
index 09dad10e82dfe5be0d22d1af1b97f1081c161fc0..b674388d33c72fd92c4e1fc92991085320eeeaf1 100644
--- a/content/designs/software-development-kit.md
+++ b/content/designs/software-development-kit.md
@@ -106,7 +106,7 @@ be cross-compiled (see the document “Apertis Build and Integration
Designâ€, section “App cross-compilationâ€). To do so, the developer would
follow the steps above with:
-1. run [][Install to target] Eclipse plugin
+1. run [Install to target]( {{< ref "#install-to-target" >}} ) Eclipse plugin
2. test package contents on device
@@ -127,13 +127,13 @@ This workflow will instead look like:
1. modify source code as needed
-2. run [][Install to target] Eclipse plugin
+2. run [Install to target]( {{< ref "#install-to-target" >}} ) Eclipse plugin
3. test package contents on device
4. if debugging is necessary, either
- 1. run [][Remote app debugging] Eclipse plugin; or
+ 1. run [Remote app debugging]( {{< ref "#remote-app-debugging" >}} ) Eclipse plugin; or
2. open secure shell (ssh) connection to target device for
multi-process or otherwise-complex debugging scenarios
@@ -182,7 +182,7 @@ single plugin.
This Eclipse plugin will check for a newer sysroot archive. If found,
the newer archive will be downloaded and installed such that it can be
-used by the [][Install to target] plugin.
+used by the [Install to target]( {{< ref "#install-to-target" >}} ) plugin.
## 3D acceleration within VirtualBox
@@ -236,11 +236,11 @@ We propose a software-based solution for generating multi-touch events
within the SDK. This will require a few new, small components, outlined
below.
-In the intended usage, the user would use the [][Multi-touch gesture generator]
+In the intended usage, the user would use the [Multi-touch gesture generator]( {{< ref "#multi-touch-gesture-generator" >}} )
to perform a gesture over an application running in the Target
Simulator as if interacting with the hardware display(s) in an Apertis
system. The Gesture Generator will then issue commands through its
-uinput device and the [][Uinput Gesture Device Xorg Driver] will use those
+uinput device and the [Uinput Gesture Device Xorg Driver]( {{< ref "#uinput-gesture-device-xorg-driver" >}} ) will use those
commands to generate native X11 multi-touch events. Applications running
within the Target Simulator will then interpret those multi-touch events
as necessary (likely through special events in the Apertis application
@@ -255,7 +255,7 @@ VirtualBox to trigger a set of multi-touch events. The generator will
draw simple graphics on the screen to indicate the type and magnitude of
the gesture as the developer drags the mouse cursor.
-
+
We anticipate the need for two gestures commonly used in popular
multi-touch user interfaces:
@@ -290,7 +290,7 @@ multi-touch user interfaces:
Additional gestures could be added during the specification process, if
necessary.
-
+
Upon the user completing the simulated gesture, the Gesture Generator
would issue a small number of key or movement events through a special
@@ -299,7 +299,7 @@ Uinput is a kernel feature which allows “userland†software (any
software which runs directly or indirectly on top of the kernel) to
issue character device actions, such as key presses, releases,
two-dimensional movement events, and so on. This uinput device will be
-interpreted by the [][Uinput Gesture Device Xorg Driver].
+interpreted by the [Uinput Gesture Device Xorg Driver]( {{< ref "#uinput-gesture-device-xorg-driver" >}} ).
#### Uinput Gesture Device Xorg Driver
@@ -322,7 +322,7 @@ hardware multi-touch pad on the host machine. This is a simpler solution
requiring less original development though it brings a risk of Windows
driver issues which would be outside of our control. Because of this, we
recommend Collabora perform further research before finalizing upon this
-solution if this is preferred over the [][Software-based solution].
+solution if this is preferred over the [Software-based solution]( {{< ref "#software-based-solution" >}} ).
The touch pad hardware would need to be well-supported in Linux but not
necessarily the host operating system (including Windows) because
@@ -378,7 +378,7 @@ minor risks:
Trackpad for their development and will share Apertis's sourcing
concerns as well.
-4. As an ultimate fallback, [][Multi-touch gesture generator] can be
+4. As an ultimate fallback, [Multi-touch gesture generator]( {{< ref "#multi-touch-gesture-generator" >}} ) can be
recommended as an alternative source of multi-touch input.
## Third-party Application Validation Tools
diff --git a/content/designs/supported-api.md b/content/designs/supported-api.md
index 0d1afbdc6f1bfe2dd554a638f6a26279369e09e7..fea22f98ccff55809d429a7f77232000253c8d19 100644
--- a/content/designs/supported-api.md
+++ b/content/designs/supported-api.md
@@ -67,7 +67,7 @@ JavaScript. In this situation, API stability requires both the C
declarations to be stable, plus the conversion of those declarations to
a GIR file to be stable — so it is affected by changes in the
implementation of the GIR scanner (the g-ir-scanner utility provided by
-gobject-introspection). This is covered further in [][ABI is not just library symbols].
+gobject-introspection). This is covered further in [ABI is not just library symbols]( {{< ref "#abi-is-not-just-library-symbols" >}} ).
## API and ABI stability strategies
@@ -425,7 +425,7 @@ libraries assigned to the Internal APIs support level, and gradually
promote them as development progresses and decisions are made. The
following sections describe the support levels.
-
+
### Custom APIs
@@ -455,7 +455,7 @@ possible. Most existing open source APIs related to core functionality
fall in this support level: Mx, clutter, clutter-gst, GStreamer, and so
```
-As discussed in section 3.5.1, [][The GTK upgrade and a Clutter API break],
+As discussed in section 3.5.1, [The GTK upgrade and a Clutter API break]( {{< ref "#the-gtk-upgrade-and-a-clutter-api-break" >}} ),
there are ways to deal with ABI/API breakage in these libraries. Keeping
both versions installed for a while is one of them. In the short term
there will be at least one set of API changes that will have a big
@@ -472,7 +472,7 @@ be ported, of course. Components that are based on Clutter such as
clutter-gst will need to be updated too. Illustration Illustration shows
how an application process could end up in this situation.
-This would lead to the kind of problems discussed in [][When a core library breaks]
+This would lead to the kind of problems discussed in [When a core library breaks]( {{< ref "#when-a-core-library-breaks" >}} )
for applications that use clutter both directly
and indirectly through another library that uses clutter under the hood,
for instance. An application that uses both SDK UI APIs and an earlier
@@ -481,7 +481,7 @@ solely on Clutter would still work fine by just having the old version
of clutter around. The same would apply to an application which relies
solely on the SDK UI APIs, of course.
-
+
### OS APIs
@@ -589,7 +589,7 @@ are reproducing here a diagram taken from the Apertis SDK documentation.
The components listed in the table below belong to the orange and green
boxes:
-
+
The following table has a list of libraries that are likely to be on
Apertis images or fit into one of the supported levels discussed before.
diff --git a/content/designs/system-updates-and-rollback.md b/content/designs/system-updates-and-rollback.md
index 5d0282e043bd958affbd15ed5f900faafe79ab15..81c349aa9807a4a9ed371452cb08f0ed55272e66 100644
--- a/content/designs/system-updates-and-rollback.md
+++ b/content/designs/system-updates-and-rollback.md
@@ -218,7 +218,7 @@ errors are detected.
Separating the system volume from the general storage volume, where
applications and user data are stored, is also recommended.
-
+
More complex schemas can be used for instance by combining OSTree
with read-only fallback partitions to handle filesystem corruption on the main
@@ -385,7 +385,7 @@ The basic workflow involves the actors below:
The following diagram shows how the data flows across services when using the
web based OSTree upgrade mechanism.
-
+
Thanks to its repository format, OSTree client devices can efficiently query
the repository status and retrieve only the changed contents without any
@@ -416,7 +416,7 @@ hawkBit](https://www.eclipse.org/hawkbit/) can happen by disabling the polling
in the OSTree updater and letting the management suite tell OSTree which commit
to download and from where through a dedicated agent running on the devices.
-
+
This has the advantage that the rollout management suite would be in complete
control of which updates should be applied to which devices, implementing
@@ -667,7 +667,7 @@ storage area, since it can be written at run-time. As a side effect of
storing the blacklist there, it will automatically be cleared if the
system is reset to a clean state.
-
+
## Implementation
@@ -685,7 +685,7 @@ The Apertis update process deals with selecting the OSTree deployment to boot,
rolling back to known-good deployments in case of failure and preparing the new
deployment on updates:
-
+
While the underlying approach differs due to the use of OSTree in Apertis over
the dual-partition approach chosen by ChromeOS and the different bootloaders,
diff --git a/content/designs/test-data-reporting.md b/content/designs/test-data-reporting.md
index dfb830e48b209913a828e7c6bb1cbbc37f434bf8..60806dba4a99ce166e60cbc4dce41beb8c790e72 100644
--- a/content/designs/test-data-reporting.md
+++ b/content/designs/test-data-reporting.md
@@ -196,7 +196,7 @@ In a single compact view, at least the following information should be available
The following is an example of how the history view might look like for test
results:
-
+
## Weekly Test Report
@@ -216,8 +216,7 @@ The report should contain at least the following data:
- Image version.
- Date of test execution.
-The report could also include the historical view as explained in the section
-[](#history-view) and allow exporting to all formats supported by the web
+The report could also include the historical view as explained in the section[history view]( {{< ref "#history-view" >}} ) and allow exporting to all formats supported by the web
application dashboard.
## Application Layout and Behaviour
diff --git a/content/designs/text-to-speech.md b/content/designs/text-to-speech.md
index 761ca93a4c96161470ae82304a534c99a96448ae..0e8d4367a99531dbf08de71a643e46f7edeac5bf 100644
--- a/content/designs/text-to-speech.md
+++ b/content/designs/text-to-speech.md
@@ -13,7 +13,7 @@ outputs = [ "html", "pdf-in",]
This documents possible approaches to designing an API for text to
speech (TTS) services for an Apertis system in a vehicle.
-This document proposes an API for the text to speech service in [][Appendix: A suggested TTS API].
+This document proposes an API for the text to speech service in [Appendix: A suggested TTS API]( {{< ref "#appendix-a-suggested-tts-api" >}} ).
This API is not finalised, and is merely a suggestion. It may be
refined in future versions of this document, or when implementation is
started.
@@ -83,8 +83,8 @@ played:
The OEM wants these policies to not be overridable by any
application-specific policy such as the ones described in
-[][New e-mail notification then going back], [][New meeting notification then cancelled],
-[][Incoming phone call].
+ [New e-mail notification then going back]( {{< ref "#new-e-mail-notification-then-going-back" >}} ), [New meeting notification then cancelled]( {{< ref "#new-meeting-notification-then-cancelled" >}} ),
+ [Incoming phone call]( {{< ref "#incoming-phone-call" >}} ).
### New e-mail notification then going back
@@ -231,8 +231,8 @@ the graphical UI, rather than making the UI more accessible.
Implement a basic TTS API with support for speaking text; and pausing,
resuming and cancelling specific requests.
-See [][News application], [][Back in a news application],
-[][New e-mail notification then going back].
+See [News application]( {{< ref "#news-application" >}} ), [Back in a news application]( {{< ref "#back-in-a-news-application" >}} ),
+ [New e-mail notification then going back]( {{< ref "#new-e-mail-notification-then-going-back" >}} ).
### Progress signalling API
@@ -247,7 +247,7 @@ UI to correspond to the output progress. For example, if a notification
is being read aloud, the notification window should be hidden when, and
only when, output is finished.
-See [][News application], [][New e-mail notification then going back]
+See [News application]( {{< ref "#news-application" >}} ), [New e-mail notification then going back]( {{< ref "#new-e-mail-notification-then-going-back" >}} )
### Output policy decided by audio manager
@@ -273,8 +273,8 @@ signal handler, a client application can ensure that TTS output is not
resumed after the stream would have been uncorked, allowing for various
resumption policies to be implemented.
-See [][New e-mail notification then going back],
-[][New meeting notification then cancelled], [][Incoming phone call].
+See [New e-mail notification then going back]( {{< ref "#new-e-mail-notification-then-going-back" >}} ),
+ [New meeting notification then cancelled]( {{< ref "#new-meeting-notification-then-cancelled" >}} ), [Incoming phone call]( {{< ref "#incoming-phone-call" >}} ).
### Output streams are mixable
@@ -283,7 +283,7 @@ multiple applications, must be mixable by the audio manager, to allow
implementing the policy of lowering the volume of one stream while
playing a more important stream over the top.
-See [][New e-mail notification].
+See [New e-mail notification]( {{< ref "#new-e-mail-notification" >}} ).
### Runtime-swappable voice backends
@@ -296,7 +296,7 @@ TTS requests queued or being output at the time a new voice backend is
selected should continue using the old voice. New TTS requests should
use the new voice.
-See [][Voice installed with the SDK], [][Voice configuration].
+See [Voice installed with the SDK]( {{< ref "#voice-installed-with-the-sdk" >}} ), [Voice configuration]( {{< ref "#voice-configuration" >}} ).
### Installable voice backends
@@ -305,14 +305,14 @@ application store; and an OEM must be able to install additional voices
before sale of a vehicle to support additional languages. These voices
must be available to choose as the default for all TTS output.
-See [][Installable voice bundle], [][Installable languages].
+See [Installable voice bundle]( {{< ref "#installable-voice-bundle" >}} ), [Installable languages]( {{< ref "#installable-languages" >}} ).
### Default SDK voice backend
A voice backend must be shipped with the SDK by default, to allow
application development against the TTS system.
-See [][Voice installed with the SDK].
+See [Voice installed with the SDK]( {{< ref "#voice-installed-with-the-sdk" >}} ).
### Voice backends are not latency sensitive
@@ -321,7 +321,7 @@ domain, which means all TTS requests would be carried over the
inter-domain communications link, incurring some latency. The TTS system
must not be sensitive to this latency.
-See [][Voice backend in the automotive domain].
+See [Voice backend in the automotive domain]( {{< ref "#voice-backend-in-the-automotive-domain" >}} ).
### System-wide voice configuration
@@ -335,7 +335,7 @@ These modifications must have limited ability to distract the driver.
For example, an application may apply a modifier to the volume of
between 0.8 and 1.2 times the current system-wide output volume.
-See [][Voice configuration].
+See [Voice configuration]( {{< ref "#voice-configuration" >}} ).
### Pronunciation data for non-phonetic words
@@ -347,7 +347,7 @@ correct pronunciation is used for the user’s current system language. If
no more suitable pronunciation is available for a word, the system must
use the current voice’s default pronunciation.
-See [][Non-phonetic place names], [][Driving abroad].
+See [Non-phonetic place names]( {{< ref "#non-phonetic-place-names" >}} ), [Driving abroad]( {{< ref "#driving-abroad" >}} ).
### Per-request language support
@@ -360,14 +360,14 @@ The system language should be used by default if the application doesn’t
specify a language, or if the specified language is not supported by the
current voice.
-See [][Driving abroad].
+See [Driving abroad]( {{< ref "#driving-abroad" >}} ).
### Support for concurrent requests
The TTS system must support accepting TTS output requests from multiple
applications concurrently, and queueing them for output sequentially.
-See [][Multiple concurrent TTS requests].
+See [Multiple concurrent TTS requests]( {{< ref "#multiple-concurrent-tts-requests" >}} ).
### Prioritisation for concurrent requests
@@ -385,7 +385,7 @@ requirement simply means that the TTS API must expose support for
prioritising requests, and must forward that prioritisation information
as ‘hints’ to whichever component implements the priority policy.
-See [][Multiple concurrent TTS requests].
+See [Multiple concurrent TTS requests]( {{< ref "#multiple-concurrent-tts-requests" >}} ).
### Output routing policy
@@ -394,7 +394,7 @@ different head units. The audio manager must be able to associate each
TTS request with an application so that it can determine which speaker
or speakers to play the audio on.
-See [][Multiple output speakers].
+See [Multiple output speakers]( {{< ref "#multiple-output-speakers" >}} ).
### Permission for using TTS system
@@ -408,8 +408,8 @@ If any TTS-specific permissions are implemented in the system, it must
be understood that an application may circumvent them by embedding its
own TTS system (or by playing pre-recorded audio files, for example).
-See [][Permissions to use TTS API],
-[][Custom TTS implementation in an application].
+See [Permissions to use TTS API]( {{< ref "#permissions-to-use-tts-api" >}} ),
+ [Custom TTS implementation in an application]( {{< ref "#custom-tts-implementation-in-an-application" >}} ).
## Existing text to speech systems
@@ -482,7 +482,7 @@ clients are not strictly separated by the server: one client can control
the settings and output for another client.
The client library has C and Python APIs. The C API is pure C, and is
-not GLib-based. The backend supports a few different voices (see [][TTS voices]):
+not GLib-based. The backend supports a few different voices (see [TTS voices]( {{< ref "#tts-voices" >}} )):
Festival, espeak, pico, and a few proprietary systems. Writing a
new voice backend, to connect an existing external voice engine to
speech-dispatcher, is not a major task.
@@ -564,10 +564,10 @@ which are available already.
## Approach
-Based on the above research ([][Existing text-to-speech systems])
-and [][Requirements], we
+Based on the above research ( [Existing text-to-speech systems]( {{< ref "#existing-text-to-speech-systems" >}} ))
+and [Requirements]( {{< ref "#requirements" >}} ), we
recommend the following approach as an initial sketch of a text to
-speech system. A suggested API for the TTS service is given in [][Appendix: A suggested TTS API].
+speech system. A suggested API for the TTS service is given in [Appendix: A suggested TTS API]( {{< ref "#appendix-a-suggested-tts-api" >}} ).
### Overall architecture
@@ -606,13 +606,13 @@ audio manager.
### Use of speech-dispatcher
-[][Speech dispatcher] is an existing FOSS system which is the
+ [Speech dispatcher]( {{< ref "#speech-dispatcher" >}} ) is an existing FOSS system which is the
standard choice for systems like this. However, it is based around a
centralised design which does not fit with our suggested architecture —
a large part of speech-dispatcher is concerned with implementing a
central daemon which handles connections and requests from multiple
clients, prioritises them, then outputs them to the audio manager. As
-described in [][Overall architecture] and [][Alternative centralised design],
+described in [Overall architecture]( {{< ref "#overall-architecture" >}} ) and [Alternative centralised design]( {{< ref "#alternative-centralised-design" >}} ),
this is functionality which our recommended design does not need.
Additionally, speech-dispatcher has the disadvantages that it:
@@ -952,54 +952,54 @@ implemented as a queue-based one from the start.
### Requirements
- - [][Basic TTS API]: Implemented as a C API on the TTS library.
+ - [Basic TTS API]( {{< ref "#basic-tts-api" >}} ): Implemented as a C API on the TTS library.
- - [][Progress signalling API]: Implemented using GObject signals
+ - [Progress signalling API]( {{< ref "#progress-signalling-api" >}} ): Implemented using GObject signals
emitted by the TTS library.
- - [][Output policy decided by audio manager]: Implemented by passing
+ - [Output policy decided by audio manager]( {{< ref "#output-policy-decided-by-audio-manager" >}} ): Implemented by passing
priority and application identifiers to the audio manager, and it
corking, uncorking, or cancelling audio streams according to its
policy, using standard PulseAudio functionality.
- - [][Output streams are mixable]: Audio manager may choose to *not*
+ - [Output streams are mixable]( {{< ref "#output-streams-are-mixable" >}} ): Audio manager may choose to *not*
cork two streams, and mix them instead.
- - [][Runtime-swappable voice backends]: TTS library loads backends
+ - [Runtime-swappable voice backends]( {{< ref "#runtime-swappable-voice-backends" >}} ): TTS library loads backends
from a directory as dynamically loaded libraries, and monitors that
directory for changes.
- - [][Installable voice backends]: Installed or symlinked into the
+ - [Installable voice backends]( {{< ref "#installable-voice-backends" >}} ): Installed or symlinked into the
backend library directory.
- - [][Default SDK voice backend]: Pico to be shipped as the default
+ - [Default SDK voice backend]( {{< ref "#default-sdk-voice-backend" >}} ): Pico to be shipped as the default
backend for the SDK.
- - [][Voice backends are not latency sensitive]: Voice backend
+ - [Voice backends are not latency sensitive]( {{< ref "#voice-backends-are-not-latency-sensitive" >}} ): Voice backend
interface uses asynchronous functions to avoid blocking the TTS
library.
- - [][System-wide voice configuration]: Stored in GSettings and read
+ - [System-wide voice configuration]( {{< ref "#system-wide-voice-configuration" >}} ): Stored in GSettings and read
by the TTS library in each application which uses it. The system
preferences application can modify the settings in GSettings.
- - [][Pronunciation data for non-phonetic words]: Provided by an API
+ - [Pronunciation data for non-phonetic words]( {{< ref "#pronunciation-data-for-non-phonetic-words" >}} ): Provided by an API
in the TTS library similar to the speech-dispatcher API for ‘sound
icons’.
- - [][Per-request language support]: Provided as a per-request API to
+ - [Per-request language support]( {{< ref "#per-request-language-support" >}} ): Provided as a per-request API to
hint at the language the source text is written in.
- - [][Support for concurrent requests]: Implemented by allowing
+ - [Support for concurrent requests]( {{< ref "#support-for-concurrent-requests" >}} ): Implemented by allowing
multiple audio channel connections to the audio manager, which
prioritises between them.
- - [][Prioritisation for concurrent requests]: Implemented by
+ - [Prioritisation for concurrent requests]( {{< ref "#prioritisation-for-concurrent-requests" >}} ): Implemented by
allowing multiple audio channel connections to the audio manager,
which prioritises between them. In-application priorities are
handled by a per-application request queue within the TTS library.
- - [][Permission for using TTS system]: Checked by the audio manager
+ - [Permission for using TTS system]( {{< ref "#permission-for-using-tts-system" >}} ): Checked by the audio manager
for each application which attempts to play audio (including TTS
output), using permissions from the application’s manifest.
@@ -1008,7 +1008,7 @@ implemented as a queue-based one from the start.
As discussed in the above sections, we recommend:
- Implementing a new TTS library, using an API like the one suggested
- in [][Appendix: A suggested TTS API]. Parts of speech-dispatcher may be used to aid the
+ in [Appendix: A suggested TTS API]( {{< ref "#appendix-a-suggested-tts-api" >}} ). Parts of speech-dispatcher may be used to aid the
implementation if appropriate.
- Implementing voice backends as dynamically loaded libraries,
diff --git a/content/designs/ui-customisation.md b/content/designs/ui-customisation.md
index fd05d5a7492446028c7374561493878b30c8948d..0f26c1b206db7d0be1ccbedc7bd6c57e88537908 100644
--- a/content/designs/ui-customisation.md
+++ b/content/designs/ui-customisation.md
@@ -17,13 +17,13 @@ the differences between variants into a UI library.
For example, below are designs of an audio player application — on the
left is variant A and on the right is the variant B.
- 
+ 
The A variant mixes three independently scrollable lists for artist,
album, and then track. The B variant uses one scrollable list with
columns for the aforementioned details. Using different widgets and
styling it should be possible to radically change the user interface as
-above. More examples of variant changes are shown in [][Variant differences].
+above. More examples of variant changes are shown in [Variant differences]( {{< ref "#variant-differences" >}} ).
The goal of standardising this process is reduce the amount of code
written or changed in customising a variant. It is understood that for
@@ -130,7 +130,7 @@ A variety of use cases for UI customisation are given below.
### Multiple Variants
Each system integrator wants to use the same user interface without
-having to rewrite from scratch (see [][Variant differences]).
+having to rewrite from scratch (see [Variant differences]( {{< ref "#variant-differences" >}} )).
For example, in the speller, variant A wants to highlight the key on an
on-screen-keyboard such that the key pops out of the keyboard, whereas
@@ -253,8 +253,8 @@ entire system.
### Prototyping
-An application author wants to prototype a UI rapidly (see [][UI prototyping]),
-using a WYSIWYG UI development tool (see [][WYSIWYG UI editing]) with access
+An application author wants to prototype a UI rapidly (see [UI prototyping]( {{< ref "#ui-prototyping" >}} )),
+using a WYSIWYG UI development tool (see [WYSIWYG UI editing]( {{< ref "#wysiwyg-ui-editing" >}} )) with access
to all the widgets in the library, including custom and vendor-specific widgets.
### Day & Night Mode
@@ -346,13 +346,13 @@ change in the user interface is not supported in Apertis.
Multiple variants should be supported on the system but the variant in
use should be decided at application compile-time such that it cannot be
-changed later (see [][Fixed variants]).
+changed later (see [Fixed variants]( {{< ref "#fixed-variants" >}} )).
### **CSS Styling**
The basic appearance of the widgets should be stylable using CSS,
changing the look and feel as much as possible with no modifications to
-the source code required (see [][Appearance customisation], [][Different icon themes]).
+the source code required (see [Appearance customisation]( {{< ref "#appearance-customisation" >}} ), [Different icon themes]( {{< ref "#different-icon-themes" >}} )).
The changes possible using CSS do not need to be incredibly intrusive
and are limited to the basic core CSS properties. For example, changing
@@ -361,7 +361,7 @@ colour scheme (background-color, color), icon theme & logos
padding).
More intrusive changes to the user interface should be achieved using
-templates (see [][Templates]) instead of CSS changes.
+templates (see [Templates]( {{< ref "#templates" >}} )) instead of CSS changes.
For example, a system integrator wants to change the colour of text in
buttons. This should be possible by changing some CSS.
@@ -370,9 +370,9 @@ buttons. This should be possible by changing some CSS.
CSS is appropriate for changing simple visual aspects of the user
interface but does not extend to allow for structural modifications to
-applications (see [][CSS styling]). Repositioning widgets or even changing
+applications (see [CSS styling]( {{< ref "#css-styling" >}} )). Repositioning widgets or even changing
which widgets are to be used is not possible with CSS and should be
-achieved using templates (see [][Templates]).
+achieved using templates (see [Templates]( {{< ref "#templates" >}} )).
There are multiple layers of widgets available for use in applications.
Starting from the lowest, simplest, level and moving higher,
@@ -398,7 +398,7 @@ look and feel across the system.
#### Catalogue of Templates
There should be a catalogue of templates provided by the library which
-system integrators can use to design their applications (see [][Template library]).
+system integrators can use to design their applications (see [Template library]( {{< ref "#template-library" >}} )).
The layouts of applications should be limited to the main use
cases.
@@ -412,7 +412,7 @@ interface library.
In addition to picking layouts from user interface library-provided
templates, it should also be possible to take existing templates and
-change them with the minimal of copy & pasting (see [][Template extension]).
+change them with the minimal of copy & pasting (see [Template extension]( {{< ref "#template-extension" >}} )).
For example, a system integrator could want to change the order of
labels in a track information view. The default order in the
@@ -427,7 +427,7 @@ modifications and minimal copy & pasting to change the order.
Templates should be as modular as possible in order to break up the
parts of a design into smaller parts. This is useful for when changes
-are required by a system integrator (see [][Templates], [][Template extension]).
+are required by a system integrator (see [Templates]( {{< ref "#templates" >}} ), [Template extension]( {{< ref "#template-extension" >}} )).
If the entire layout is in one template, it is difficult to make small
changes without having to copy the entire original template.
@@ -439,7 +439,7 @@ template.
#### Custom Widgets in Templates
A system integrator should be able to use custom widgets they have
-written for the particular variant in the template format (see [][Custom widget usage]).
+written for the particular variant in the template format (see [Custom widget usage]( {{< ref "#custom-widget-usage" >}} )).
The responsibility of compatibility with the rest of the
user interface of custom widgets is on the widget author.
@@ -447,7 +447,7 @@ user interface of custom widgets is on the widget author.
With a library of widgets and models available to the system integrator,
the options of widgets and ways to interact with them should be well
-documented (see [][Template library]). If signals, signal callbacks, and
+documented (see [Template library]( {{< ref "#template-library" >}} )). If signals, signal callbacks, and
properties are provided these should all be listed in the documentation
for the system integrator to connect to properly.
@@ -490,10 +490,10 @@ once and then can be shared among other applications.
There should be a functional separation between data provider (*model*),
the way in which it is displayed in the user interface (*view*), and the
widgets for interaction and data manipulation (*controller*) (see
-example in [][Templates]). The model should be a separate object not
+example in [Templates]( {{< ref "#templates" >}} )). The model should be a separate object not
depending on any visual aspect of the widget.
-Following on from the previous example (in [][Templates]), the model would
+Following on from the previous example (in [Templates]( {{< ref "#templates" >}} )), the model would
be the list of pictures on the system, and the two variants would use
different widgets, but would attach the same model to each widget. This
is the key behind being able to swap one widget for another without
@@ -507,13 +507,13 @@ the *model* in that it provides the data to fill said model.
All widgets should be linked into a language translation system such
that it is trivial not only for the user to change language (see
-[][Language]), but also for new translations to be added and existing
-translations updated (see [][Ota updates]).
+ [Language]( {{< ref "#language" >}} )), but also for new translations to be added and existing
+translations updated (see [Ota updates]( {{< ref "#ota-updates" >}} )).
### Animations
Animations in use in widgets should be configurable by the system
-integrator (see [][Animations] for examples). These animations should be
+integrator (see [Animations]( {{< ref "#animations" >}} ) for examples). These animations should be
used widely across the system to ensure a consistent experience.
Applications should expose a fixed set of transitions which can be
animated so system integrators can tell what can be customised.
@@ -523,18 +523,18 @@ animated so system integrators can tell what can be customised.
The widgets and templates should be usable from a UI design format, such
as [GtkBuilder] or [ClutterScript]. This includes custom widgets. This would
enable application authors to quickly prototype applications
-(see [][Prototyping]).
+(see [Prototyping]( {{< ref "#prototyping" >}} )).
### Day & Night Mode
The user interface should change between light and dark mode when
outside the vehicle becomes dark in order to not shine too brightly and
-distract the user (see [][Day night mode]).
+distract the user (see [Day night mode]( {{< ref "#day--night-mode" >}} )).
### View Management
-A method of managing application views (see [][View]) should be provided to
-application authors (see [][View management]). On startup the application
+A method of managing application views (see [View]( {{< ref "#view" >}} )) should be provided to
+application authors (see [View management]( {{< ref "#view-management" >}} )). On startup the application
should provide its views to the view manager. From this point on the
responsibility of constructing views, switching views, and showing view
animations should be that of the view manager. The view manager should
@@ -544,12 +544,12 @@ usage so not load all views simultaneously.
### Speed Lock
Some features and certain behaviour in the user interface should be
-disabled or modified respectively when the vehicle is moving (see [][Speed lock]).
+disabled or modified respectively when the vehicle is moving (see [Speed lock]( {{< ref "#speed-lock" >}} )).
It should be possible to customise whether each item listed below
is disabled or not as it can depend on the target market of the vehicle
-(see [][Geographical customisation]). Additionally, it should be up to the
+(see [Geographical customisation]( {{< ref "#geographical-customisation" >}} )). Additionally, it should be up to the
system to enforce the disabling of the following features and should not
-be left completely up to application authors (see [][System enforcement]).
+be left completely up to application authors (see [System enforcement]( {{< ref "#system-enforcement" >}} )).
#### Scrolling Lists
@@ -603,7 +603,7 @@ audio continues to sound).
#### Map Gestures
-As with kinetic scrolling in lists (see [][Scrolling lists]), the gestures
+As with kinetic scrolling in lists (see [Scrolling lists]( {{< ref "#scrolling-lists" >}} )), the gestures
in the map widget should make fewer visual changes and reduce the number
of distractions for the user. Similar to the kinetic scroll example, the
map view should move by a fixed distance instead of following the user’s
@@ -626,7 +626,7 @@ The goal of templates is to allow an application developer to change the
user interface of their application without having to changing the
source code. These are merely templates and have no way of implementing
logic (if/else statements). If this is required, widget code
-customisation is required (see [][Custom widgets]).
+customisation is required (see [Custom widgets]( {{< ref "#custom-widgets" >}} )).
#### Specification in ClutterScript
@@ -731,7 +731,7 @@ the A-variant application chooser are:
These are just two examples of how an application chooser could be
designed. The user interface files contain minimal theming as that is
-achieved in separate CSS files (see [][Theming]).
+achieved in separate CSS files (see [Theming]( {{< ref "#theming" >}} )).
Typically, applications will come with many templates for system
integrators to either use, or take guidance from.
@@ -858,7 +858,7 @@ In this example, this object has three children:
In these examples, the `external-uri` used the `file://` URI scheme, but
others supported by GIO can be used. For example, templates in
-[][GResources] can be used using the `resource://` URI
+ [GResources]( {{< ref "#gresources" >}} ) can be used using the `resource://` URI
scheme.
Application authors should not use templates and inheritance excessively
@@ -975,13 +975,13 @@ my_roller_class_init (MyRollerClass *klass)
In the template, this variant would stop referring to `LightwoodRoller`
and instead would use `MyRoller`, or update the widget factory entry (see
-[][Widget factories]).
+ [Widget factories]( {{< ref "#widget-factories" >}} )).
### Models
Data that is to be displayed to the user in list widgets should be
stored in an orthogonal model object. This object should have no
-dependency on anything visual (see [][MVC separation]).
+dependency on anything visual (see [MVC separation]( {{< ref "#mvc-separation" >}} )).
The actual implementation of the model should be of no importance to the
widgets, and only basic model interface methods should be called by any
@@ -1086,24 +1086,24 @@ little to modify to support the speed lock. Apertis widgets should read
and monitor the GSettings key to change their content when necessary:
- Lists with kinetic scrolling – disable the kinetic scrolling (see
- [][Scrolling lists]).
+ [Scrolling lists]( {{< ref "#scrolling-lists" >}} )).
- Text – very long texts in text views or label widgets should be
- hidden if there is no alternative provided (see [][Text]).
+ hidden if there is no alternative provided (see [Text]( {{< ref "#text" >}} )).
- Keyboard – do not show the keyboard and provide feedback to the
application as to whether the keyboard could appear or not (see
- [][Keyboard]).
+ [Keyboard]( {{< ref "#keyboard" >}} )).
- Pictures – mast the picture shown in the picture widget (see
- [][Pictures]).
+ [Pictures]( {{< ref "#pictures" >}} )).
- Video playback – either pause the video completely or just mask the
- video and keep the audio sounding (see [][Video playback]).
+ video and keep the audio sounding (see [Video playback]( {{< ref "#video-playback" >}} )).
- - Map – disable the kinetic scrolling (see [][Map gestures]).
+ - Map – disable the kinetic scrolling (see [Map gestures]( {{< ref "#map-gestures" >}} )).
- - Web view – mask the contents entirely (see [][Web view]).
+ - Web view – mask the contents entirely (see [Web view]( {{< ref "#web-view" >}} )).
Apertis widgets should fill text widgets with contents that can
differ depending on whether the speed lock is active or not.
@@ -1111,17 +1111,17 @@ differ depending on whether the speed lock is active or not.
#### List Columns
The number of columns visible should be reduced to remove superfluous
-information when the speed lock is active (see [][List columns]). The nature
+information when the speed lock is active (see [List columns]( {{< ref "#list-columns" >}} )). The nature
of every list can be different and the detection of superfluous
information is impossible automatically. There should be a way of either
application authors specifying which columns should be hidden, or it
should be left up to the application itself. If the latter is not an
-option (see enforcement comments in [][Speed lock]), the entire list widget
+option (see enforcement comments in [Speed lock]( {{< ref "#speed-lock" >}} )), the entire list widget
should be masked to hide its contents.
#### Keyboard
-As mentioned in [][Keyboard], applications
+As mentioned in [Keyboard]( {{< ref "#keyboard" >}} ), applications
should deal with the possibility that the keyboard may not be available
at any given time, if the speed lock is active. In the case that
the keyboard request is denied, the application should change its user
@@ -1140,7 +1140,7 @@ accordingly.
#### Insensitive Widgets
-As highlighted in [][Insensitive widgets], it should be made obvious to the
+As highlighted in [Insensitive widgets]( {{< ref "#insensitive-widgets" >}} ), it should be made obvious to the
user when functionality is disabled, and why. There should be a uniform
visual change to widgets when they have been made insensitive so users
can immediately recognise what is happening.
@@ -1287,7 +1287,7 @@ the A-variant application chooser are:
These are just two examples of how an application chooser could be
designed. The user interface files contain minimal theming as that is
-achieved in separate CSS files (see [][Theming]).
+achieved in separate CSS files (see [Theming]( {{< ref "#theming" >}} )).
Typically, applications will come with many templates for system
integrators to either use, or take guidance from.
@@ -1310,7 +1310,7 @@ to find examples of it in the source code.
#### Thumbnail View
- 
+ 
- Re-used:
@@ -1326,7 +1326,7 @@ to find examples of it in the source code.
#### Detail View
- 
+ 
- Re-used: nothing
@@ -1339,7 +1339,7 @@ to find examples of it in the source code.
#### List View
- 
+ 
- Re-used: nothing
@@ -1351,7 +1351,7 @@ to find examples of it in the source code.
#### Full Screen
- 
+ 
- Re-used: nothing
diff --git a/content/designs/x86-build-infrastructure.md b/content/designs/x86-build-infrastructure.md
index ea4e7a4d3dc40cf002bc65beeaec91d907733f19..b4a2383c4b347335475cbf8c15823ca561e221c4 100644
--- a/content/designs/x86-build-infrastructure.md
+++ b/content/designs/x86-build-infrastructure.md
@@ -124,7 +124,7 @@ Each CPU instruction set is marked by the codename used by OBS:
* `armv7hl`: the ARMv7 32 bit Hard Float ISA, also known as `armhf` in Debian
* `aarch64`: the ARMv8 64 bit ISA, also known as `arm64` in Debian
-
+
Particularly relevant here are the `armv7hl` jobs building ARMv7 32 bit packages
that can be dispatched to: