Commit 18d0ef0f authored by Martyn Welch's avatar Martyn Welch Committed by Emanuele Aina

Updates and clarifications for hwpack requirements

Updates and clarifications based on comments from first round of review:

- Better describe the OSpack and HWpack as concepts rather than specific
  artefacts.
- Clarify that packaging is done using Debian packaging.
- Clarify when development of a HWpack may lead to OSpack modifications.
Signed-off-by: default avatarMartyn Welch <martyn.welch@collabora.com>
parent db9f57a5
......@@ -15,27 +15,27 @@ This documentation covers the requirements and considerations that should be tak
This section briefly covers the concepts and expectations of the Apertis platform.
### Components
### Image Building Stages
Apertis images are built from binary packages, packaged in the `.deb` format. Building these packages is expected to be carried out from source by the Apertis infrastructure, ensuring all packages dependencies are properly described and reducing the risk of unexpected dependencies.
These packages are usually assembled into 2 bigger building blocks, the `OSpack` and the `HWpack`.
The selection and packaging of these packages are predominantly driven by the needs of the two main process steps required to create images, known as the `OSpack` and `HWpack`.
#### OSpack
The OSpack is a generic (architecture specific but largely hardware independent) archived rootfs built from Apertis packages. The process is managed by a tool called [Debos](https://github.com/go-debos/debos), which uses yaml configuration files to guide what steps it takes. Apertis provides yaml files to assemble a number of differently targeted OSpacks, ranging from a minimal GUI-less OSpack, a target focused GUI OSpack and a development environment with a desktop style GUI.
The OSpack stage generates one or more generic (architecture specific but largely hardware independent) archived rootfs built from Apertis packages. These rootfs archives are known as OSpacks. The process is managed by a tool called [Debos](https://github.com/go-debos/debos), which uses yaml configuration files to guide what steps it takes. Apertis provides yaml files to assemble a number of differently targeted OSpacks, ranging from a minimal GUI-less OSpack, a target focused GUI OSpack and a development environment with a desktop style GUI and has pre-packaged the components required to generate these OSpacks.
![OSpack creation with Debos](./media/debos-ospack.svg)
#### HWpack
Unlike some of the other items described here, the hardware pack (HWpack) is not a single item. The HWpack is one of a number of packages and processes, controlled via a Debos script, that convert a hardware independent OSpack into an image which can be successfully booted on a specific hardware platform.
Unlike the OSpack step, the hardware package (HWpack) step does not result in an item known as a HWpack. The HWpack is comprised of a Debos script which controls the processing of a run time determined OSpack to convert it from a hardware independent OSpack into an image which can be successfully booted on a specific hardware platform. In addition to developing the HWpack script, the HWpack step requires the modification and packaging of the required components to perform this transformation.
![Image creation with Debos](./media/debos-image.svg)
### Apertis packages
Apertis standardizes on a specific set of components (with specific versions) and technologies to fulfill the needs of the target platforms. This maximizes sharing and reuse, thus minimizing effort and cost of maintaining common components across products. Deviations from the standard selection may be needed to accommodate product-specific needs but such deviations tend to reduce reuse and thus increase the long-term maintenance efforts. It will likely fall on the product team in question to carry this added effort.
Apertis standardizes on a specific set of components (with specific versions) and technologies to fulfill the needs of the target platforms. This maximizes sharing and reuse, thus minimizing effort and cost of maintaining common components across products. Deviations from the standard selection may be needed to accommodate product-specific needs but such deviations tend to reduce reuse and thus increase the long-term maintenance efforts. It will likely fall on the product team in question to carry this added effort. As a result, it is strongly preferred for deviations to be minimized with generic improvements and additions made to the standard components to add the required functionality where possible.
The components selected as part of the base Apertis system need to meet a number of project criteria.
......@@ -56,7 +56,9 @@ These are some of the key packages from which the Apertis system is built:
- Wayland
- Mesa
- PulseAudio
All Apertis packages are packaged using standard Debian packaging, with source code and package configuration stored in the Apertis GitLab enabling automation of the package build process.
### Typical Apertis OS layout
The reference Apertis images share a common layout per architecture, enabling images to be shared across the various supported platforms of each architecture:
......@@ -66,9 +68,11 @@ The reference Apertis images share a common layout per architecture, enabling im
It is expected that the requirements and practicalities of products based on Apertis will require deviations to be made from this layout. Such deviations however should be carefully considered. Some, such as storing the bootloader at the beginning of the same medium as the rootfs, carry very little impact as far as the functionality of Apertis is concerned. Others such as using a different bootloader, storing the kernel outside of the rootfs or using a different update strategy (such as A/B partitioning) may pose in a non-trivial effort for integration, loss of some Apertis functionality and/or extra on-going maintenance effort.
The OSpack is expected to contain common functionality to enable use of supported hardware, for example the OSpacks which are intended to be used with an operational graphical environment include Wayland, though the hardware specific drivers are in the HWpacks. When enabling new types of functionality, it is expected that generic support would be added to the OSpacks where applicable. If such functionality is widely used, this should be integrated into the Apertis OSpacks. Support for niche functionality, or functionality not of general interest to Apertis, will need to be added to a product specific OSpack.
# HWpack Components
As with the OSpack (and unless specific exceptions provided) all components should be properly packaged and provided with source to enable debugging, extension and further optimization. It is expected that some changes may be viable to be included in the main Apertis packages, others will need bespoke packages which would typically be stored in a dedicated project area, as described in the [contribution process](https://designs.apertis.org/latest/contribution-process.html) document.
As with the OSpack (and unless specific exceptions provided) all components should be properly packaged and provided with source to enable debugging, extension and further optimization. It is expected that some changes may be viable to be included in the main Apertis packages, some packages may be added to the main Apertis package repositories and others will need bespoke packages which would typically be stored in a dedicated project area, as described in the [contribution process](https://designs.apertis.org/latest/contribution-process.html) document. It is typical for the following areas to need modifications or to be provided, though other modifications may also be required.
## Bootloader
......@@ -100,16 +104,16 @@ For development purposes, the kernel should provide early serial debugging and b
## Firmware
It is understood that many hardware platforms may need firmware, provided by the vendor as binaries, to use certain functionality provided by the device. It is still expected that such firmware is packaged as a deb package, though it is understood that source will not be available for such components.
It is understood that many hardware platforms may need firmware, provided by the vendor as binaries, to use certain functionality provided by the device. It is still expected that such firmware is packaged as a deb package, though it is understood that source will not be available for such components. The Apertis infrastructure should still be used to build the binary packages.
## Debos .yaml configuration
Apertis uses Debos to automate the conversion of binary packages into images suitable for installation on specific targets in several stages. The configuration used for the Apertis reference platforms can be found in [GitLab](https://gitlab.apertis.org/infrastructure/apertis-image-recipes) with their use documented in `README.md`. It is expected that a HWpack contains configuration file(s) that:
Apertis uses Debos to automate the conversion of binary packages into images suitable for installation on specific targets in several stages. The configuration used for the Apertis reference platforms can be found in [GitLab](https://gitlab.apertis.org/infrastructure/apertis-image-recipes) with their use documented in `README.md`. It is expected that a HWpack provides configuration file(s) that:
- Generate the required image(s) from either a reference or project specific OSpack
- Generate images containing the partitioning expected by the target and project
- Add any extra components needed via the installation of packages
- Are provided with any scripts required to aid in the application of minor changes to tweak the image to required default configuration
- Generate any project specific OSpacks as agreed with the relevant project
- Generate any project specific OSpacks when sufficient support can't be added to the generic OSpack recipes to cover the functionality required by the relevant project.
### Documentation
......
......@@ -90,7 +90,7 @@
<rect class="BoundingBox" stroke="none" fill="none" x="10934" y="3354" width="2749" height="1213"/>
<path fill="rgb(255,255,255)" stroke="none" d="M 12308,4536 L 10964,4536 10964,3384 13652,3384 13652,4536 12308,4536 Z"/>
<path fill="none" stroke="rgb(58,90,128)" stroke-width="60" stroke-linejoin="round" d="M 12308,4536 L 10964,4536 10964,3384 13652,3384 13652,4536 12308,4536 Z"/>
<text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="388px" font-weight="400"><tspan class="TextPosition" x="11766" y="3879"><tspan fill="rgb(90,90,90)" stroke="none">Image</tspan></tspan></tspan><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="388px" font-weight="400"><tspan class="TextPosition" x="11152" y="4311"><tspan fill="rgb(90,90,90)" stroke="none">Configuration</tspan></tspan></tspan></text>
<text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="388px" font-weight="400"><tspan class="TextPosition" x="11566" y="3879"><tspan fill="rgb(90,90,90)" stroke="none">HWpack</tspan></tspan></tspan><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="388px" font-weight="400"><tspan class="TextPosition" x="11152" y="4311"><tspan fill="rgb(90,90,90)" stroke="none">Configuration</tspan></tspan></tspan></text>
</g>
</g>
<g class="com.sun.star.drawing.CustomShape">
......@@ -146,4 +146,4 @@
</g>
</g>
</g>
</svg>
\ No newline at end of file
</svg>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment