Commit 7e20dd26 authored by Richard Neill's avatar Richard Neill
Browse files

doc: Add guidance for migrating to later EWAOL releases



Issue-Id: SCM-4394
Signed-off-by: Richard Neill's avatarRichard Neill <richard.neill@arm.com>
Change-Id: I7ceda85d27772ba71ca26ab24684edef37e1c0db
parent 3718792f
......@@ -154,7 +154,9 @@ The documentation is structured as follows:
Provides guidance for configuring, building, and deploying EWAOL
distributions on supported target platforms, running and validating
supported EWAOL functionalities, and running the distribution on custom
hardware.
hardware. Also includes migration guidance for how to enable these
activities on a later EWAOL release, when upgrading from an older release
version.
* :ref:`Developer Manual <manual/index:Developer Manual>`
......
......@@ -11,6 +11,8 @@ This section of the User Guide describes how to extend EWAOL in order to
configure and build it for deployment on custom or unsupported target platforms,
via kas.
.. _user_guide_extend_porting:
****************************************************************
Porting EWAOL to a Custom or Unsupported Target Platform via kas
****************************************************************
......
......@@ -24,3 +24,11 @@ features, and running example EWAOL use-cases.
Describes how to extend the EWAOL project to build and run on a custom or
unsupported target platform.
.. toctree::
:maxdepth: 1
migration
Guidance for migrating an existing EWAOL build environment to a later EWAOL
release.
..
# Copyright (c) 2022, Arm Limited.
#
# SPDX-License-Identifier: MIT
###########################
Migrating to Later Releases
###########################
This page describes guidance for updating a user's build environment and
processes from those required to use a previous EWAOL release, to instead setup
and use a later EWAOL release, as part of a migration process.
Details of the EWAOL release process can be found at
:ref:`Codeline Management <codeline_management:Codeline Management>`, and a
summary of each release can be found at
:ref:`Changelog & Release Notes <changelog:Changelog & Release Notes>`.
The following migration guidance is described such that the required changes are
with respect to the previous EWAOL release. The processes are categorized
according to the associated section of the user-guide documentation.
***************************
To |v1.0:migration version|
***************************
After following the below guidance to transition to EWAOL
:substitution-code:`|v1.0:migration version|`, boot the resulting image to run
and validate the release.
EWAOL Reproduce Migration
=========================
Build Host Setup
----------------
* The list of essential packages and package versions for the associated release
of the Yocto Project was updated. Refer to the
|list of essential packages|_ documentation to ensure the necessary
packages are installed and upgraded to support the migration.
* The supported version of the ``kas`` build tool was updated to
:substitution-code:`|v1.0:kas version|`. See
:ref:`Build Host Environment Setup<user_guide_reproduce_environment_setup>`
for guidance on installing this version of ``kas``.
Download
--------
* To migrate to :substitution-code:`|v1.0:migration version|`, it is necessary
to download that version of the ``meta-ewaol`` repository source. To do this,
either clone the repository into a new directory by following the instructions
given in :ref:`Download<user_guide_reproduce_download>`, or update the
existing local repository by switching to the
:substitution-code:`|v1.0:migration version|` tag using Git.
Build
-----
* The kas configuration files provided to build and customize EWAOL distribution
images have been updated, and it is necessary to supply them to the kas build
tool in a particular order. Therefore, to build the later version of EWAOL,
refer to the :ref:`Build Documentation<user_guide_reproduce_build>`.
* If working from an existing local ``meta-ewaol`` repository that was switched
to the :substitution-code:`|v1.0:migration version|` release but has artifacts
remaining from previous builds, ensure that there are no locally staged
changes to the dependent layers so that the kas build tool can successfully
update them.
Deploy
------
* :substitution-code:`|v1.0:migration version|` introduces new types of EWAOL
distribution images, and the resulting filenames and paths are therefore
different than previous releases. Check the
:ref:`Build<user_guide_reproduce_build>` and
:ref:`Deploy<user_guide_reproduce_deploy>` sections of the release
documentation for the new filenames produced during the build, and which
should be deployed to the target platform.
EWAOL Extend Migration
======================
Porting
-------
* If migrating to EWAOL :substitution-code:`|v1.0:migration version|` as part of
porting to a custom or unsupported target platform, it is necessary to change
the existing custom kas configuration file for the target platform to use the
correct kas configuration files, and supply them with the correct ordering in
the ``includes`` YAML section. In addition, the ``meta-ewaol`` repository
definition must be set to use the
:substitution-code:`|v1.0:migration version|` release tag in ``refspec:``.
See :ref:`Porting<user_guide_extend_porting>` for details of the necessary
configuration.
......@@ -17,7 +17,7 @@ Introduction
************
The recommended approach for image build setup and customization is to use the
`kas build tool`_. To support this, EWAOL provides configuration files to setup
|kas build tool|_. To support this, EWAOL provides configuration files to setup
and build different target images, different distribution image features, and
set associated parameter configurations.
......@@ -78,6 +78,8 @@ and one **Target Platform Config** to the kas build tool, chained via a colon
In the next section, guidance is provided for configuring, building and
deploying EWAOL distributions using these kas configuration files.
.. _user_guide_reproduce_environment_setup:
****************************
Build Host Environment Setup
****************************
......@@ -112,6 +114,8 @@ User Guide uses ``bmap-tools``. This can be installed via:
EWAOL baremetal distribution image, or at least 100 GBytes of free disk space
to build an EWAOL virtualization distribution image.
.. _user_guide_reproduce_download:
********
Download
********
......@@ -146,7 +150,7 @@ To build a baremetal distribution image for the N1SDP hardware target platform:
.. code-block:: console
kas build meta-ewaol-config/kas/baremetal.yml:meta-ewaol-config/kas/n1sdp.yml
kas build --update meta-ewaol-config/kas/baremetal.yml:meta-ewaol-config/kas/n1sdp.yml
The resulting baremetal distribution image will be produced at:
``build/tmp_baremetal/deploy/images/n1sdp/ewaol-baremetal-image-n1sdp.*``
......@@ -156,7 +160,7 @@ hardware target platform:
.. code-block:: console
kas build meta-ewaol-config/kas/baremetal-sdk.yml:meta-ewaol-config/kas/n1sdp.yml
kas build --update meta-ewaol-config/kas/baremetal-sdk.yml:meta-ewaol-config/kas/n1sdp.yml
The resulting baremetal distribution image will be produced at:
``build/tmp_baremetal/deploy/images/n1sdp/ewaol-baremetal-sdk-image-n1sdp.*``
......@@ -179,7 +183,7 @@ platform:
.. code-block:: console
kas build meta-ewaol-config/kas/virtualization.yml:meta-ewaol-config/kas/n1sdp.yml
kas build --update meta-ewaol-config/kas/virtualization.yml:meta-ewaol-config/kas/n1sdp.yml
The resulting virtualization distribution image will be produced:
``build/tmp_virtualization/deploy/images/n1sdp/ewaol-virtualization-image-n1sdp.*``
......@@ -189,7 +193,7 @@ hardware target platform:
.. code-block:: console
kas build meta-ewaol-config/kas/virtualization-sdk.yml:meta-ewaol-config/kas/n1sdp.yml
kas build --update meta-ewaol-config/kas/virtualization-sdk.yml:meta-ewaol-config/kas/n1sdp.yml
The resulting virtualization distribution image will be produced:
``build/tmp_virtualization/deploy/images/n1sdp/ewaol-virtualization-sdk-image-n1sdp.*``
......@@ -223,12 +227,14 @@ for its Guest VM, run:
.. code-block:: console
EWAOL_GUEST_VM1_NUMBER_OF_CPUS=8 kas build meta-ewaol-config/kas/virtualization.yml:meta-ewaol-config/kas/n1sdp.yml
EWAOL_GUEST_VM1_NUMBER_OF_CPUS=8 kas build --update meta-ewaol-config/kas/virtualization.yml:meta-ewaol-config/kas/n1sdp.yml
EWAOL supports adding multiple independently-configurable Guest VMs to a
virtualization distribution image. Additional details for this are provided at
:ref:`manual_build_system_virtualization_customization`.
.. _user_guide_reproduce_deploy:
******
Deploy
******
......
......@@ -96,6 +96,8 @@ other_definitions = {
# Potentially old definitions required for documenting migrations, changelog
release_definitions = {
"v1.0:migration version": "v1.0",
"v1.0:kas version": other_definitions["kas version"],
}
def generate_link(key, link):
......
......@@ -35,6 +35,7 @@ container-engine-integration-tests.bb
containerization
containerized
containers_kernelcfg_check.bbclass
contributing_documentation_build_validation
customization
customizations
datetime
......@@ -74,6 +75,7 @@ ewaol-specific
ewaol-test
ewaol-virtualization
ewaol-virtualization-image
ewaol-virtualization-n1sdp-efidisk.wks.in
ewaol-virtualization-sdk-image
extensible
filenames
......@@ -165,6 +167,7 @@ quickstart
readme.md
refactor
refactored
refspec
repository's
restructuredtext
return_code
......@@ -218,7 +221,9 @@ use-cases
user_accounts
user-accounts-integration-tests.bb
user_guide
user_guide_reproduce_environment_setup
v
v1.0
v1.20.11+k3s2
validations
virt_test_clean_env
......
Supports Markdown
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