Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Cleanup reference manual lmp section #633

Merged
merged 1 commit into from
Dec 13, 2023
Merged

Cleanup reference manual lmp section #633

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -414,6 +414,8 @@
"community-factory/create-factory": "../getting-started/signup/index.html",
"community-factory/": "index.html",
"getting-started/git-config/index": "../install-fioctl/index.html#configuring-git",
"reference-manual/linux/linux-building": "../../user-guide/lmp-customization/linux-building.html",
"reference-manual/linux/linux-extending": "../../user-guide/lmp-customization/linux-extending.html",
}

# Make external links open in a new tab.
Expand Down
2 changes: 1 addition & 1 deletion source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®.
user-guide/account-management/account-management
user-guide/containers-and-docker/index
user-guide/custom-ci/custom-ci
user-guide/lmp-customization/lmp-customization
user-guide/lmp-customization/index
user-guide/lmp-auto-hostname/lmp-auto-hostname
user-guide/lmp-device-auto-register/lmp-device-auto-register
user-guide/foundriesio-rest-api/foundriesio-rest-api
Expand Down
55 changes: 21 additions & 34 deletions source/reference-manual/linux/building-sdk.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _ref-building-sdk:

Building SDK
============
Building The Yocto Project Standard SDK
=======================================

The Yocto Project Standard SDK is a development environment composed by:

Expand All @@ -11,36 +11,25 @@

The SDK is used to replicate the tools and files from the target image,
but without depending on BitBake.
For details on what the SDK is
and a complete description of how to work with it,
visit
`Yocto Project Application Development and the Extensible Software Development Kit <https://docs.yoctoproject.org/kirkstone/sdk-manual/index.html>`_.

The LmP can be configured to
create an SDK install script of the same rootfs image
built by the CI.
The SDK install script is created by
``bitbake <image> -c populate_sdk``.

When the ``lmp:params:BUILD_SDK`` is set
and a new target is created,
For details on what the SDK is, and a complete description of how to work with it,

Check warning on line 14 in source/reference-manual/linux/building-sdk.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/linux/building-sdk.rst", "range": {"start": {"line": 14, "column": 1}}}, "severity": "INFO"}
visit `Yocto Project Application Development and the Extensible Software Development Kit <https://docs.yoctoproject.org/kirkstone/sdk-manual/index.html>`_.

The LmP can be configured to create an SDK install script of the same rootfs image built by the CI.
The SDK install script is created by ``bitbake <image> -c populate_sdk``.

When the ``lmp:params:BUILD_SDK`` is set and a new target is created,
the SDK install script is also built.

This configuration increases the build time,
so enable the variable
only when a new SDK install script is needed.
This configuration increases the build time, so enable it only when a new SDK install script is needed.

Change the file
``ci-scripts/factory-config.yml``
to include the variable ``BUILD_SDK: "1"``
whenever a new SDK install script is needed,
as the following example.
Change ``ci-scripts/factory-config.yml`` to include the variable ``BUILD_SDK: "1"``.
Do this whenever a new SDK install script is needed:

.. prompt:: text

lmp:
params:
BUILD_SDK: "1"
lmp:
params:
BUILD_SDK: "1"

The SDK image is available under the ``SDK`` folder.

Expand All @@ -52,8 +41,7 @@
Installation
------------

After downloading the SDK install script,
you can install it in any folder.
After downloading the SDK install script, you can install it in any folder.
In this example, we use ``/usr/local/cortexa53-crypto``.

.. prompt:: text
Expand All @@ -68,7 +56,7 @@
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.

After the installation, the resultant folder has the ``sysroots`` for the host and target architecture.
After installation, the resultant folder has the ``sysroots`` for the host and target architecture.
It also contains the script used to setup the environment to work with the SDK:

.. prompt:: text
Expand Down Expand Up @@ -97,12 +85,11 @@
$ file helloworld
helloworld: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=80e241327bd3412b91c2035cbacb73e87797e0b5, for GNU/Linux 3.14.0, with debug_info, not stripped

With the exported environment variable,
it is possible to build using the toolchain
With the exported environment variable, it is possible to build using the toolchain
and, when needed, to use the header or other files from the ``sysroots``.

In the example, we see that the generated file can not be executed on the host machine.
Using ``file``, we learn this is because the binary is for ``ARM aarch64`` architecture.
In the example, we saw that the generated file can not be executed on the host machine.
Using ``file``, we learned that this is because the binary is for ``ARM aarch64`` architecture.

For more information regarding Standard SDK, follow the Yocto Project
For more information regarding the Standard SDK, follow the Yocto Project
`instructions <https://docs.yoctoproject.org/kirkstone/singleindex.html#using-the-sdk-toolchain-directly>`_.
27 changes: 15 additions & 12 deletions source/reference-manual/linux/development-tags.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,34 @@
.. _ref-development-tags:

Understanding Development FIO Tags
Understanding FIO Development Tags
==================================

When Foundries.io adds a patch to a repository with an upstream, we add an ``FIO``
tag in the Git shortlog to make the commit easy to see. For example, in
Foundries.io U-Boot tree::
When Foundries.io™ adds a patch to a repository with an upstream, we add a ``FIO`` tag in the Git shortlog.
This makes the commit easier to see.
For example, in our U-Boot tree::

[FIO internal] common: foundries.io verified boot utility

The most common used tags through the Foundries.io repositories are:
The most common tags used throughout the repositories are:

* ``[FIO fromtree]``: patches cherry-picked, rather than merged, from upstream (mainline)
* ``[FIO fromlist]``: patches submitted to upstream for review (in mailing lists, pending PRs etc.), and revisions to them
* ``[FIO toup]``: patches that want to go upstream
* ``[FIO temphack]`` or ``[FIO hack]``: temporary patches that keep things working for now but need a better solution later for upstreaming
* ``[FIO extras]``: patches pulled in for specific functionality that are useful for subscribers, but not critical
* ``[FIO temphack]`` or ``[FIO hack]``: temporary patches that keep things working for now, but need a better solution later for upstreaming
* ``[FIO extras]``: non-critical patches pulled in for extra, potentially useful functionality
* ``[FIO internal]``: patches needed by the LmP, not intended for upstream use
* ``[FIO squash]``: patch should be squashed with an original patch, fixing possible issues in that patch. This tag requires a commit message tag "Fixes:" filled out properly
* ``[FIO squash]``: patch should be squashed with an original patch, fixing possible issues in that patch.
This tag requires a commit message tag ``Fixes:`` to be filled out properly

There are also exceptional tags for patches that were cherry-picked/sent from/to SoC vendor forks:

* ``[FIO from<vendor_name>]``: patches cherry-picked from ``<vendor_name>`` forked tree, for example ``[FIO fromnxp]``
* ``[FIO to<vendor_name>]``: patches, that want to go to SoC vendor forked tree, for example ``[FIO tostm]``
* ``[FIO to<vendor_name>-altered]``: exceptional case, when not a whole patch was cherry-picked, but rather some parts or it was completely reimplemented. In this case ``-altered`` is added, for example ``[FIO fromnxp-altered]``
* ``[FIO to<vendor_name>-altered]``: exceptional case, when not a whole patch was cherry-picked, but rather some parts or it was completely reimplemented.
In this case ``-altered`` is added, for example ``[FIO fromnxp-altered]``


.. important:: When a patch is cherry-picked, the Git cherry-pick command should be invoked with ``-x`` (append commit name) parameter, so
the original commit hash is added to the new commit message (for example ``(cherry-picked from commit 1e24c2671acdbcf81207c43da39e09846f404dc3)``).
With a hash, tracking the original commit in a mainline/SoC vendor tree is much easier.
.. important:: When a patch is cherry-picked, the Git cherry-pick command should be invoked with ``-x`` (append commit name) parameter.
This is so that the original commit hash is added to the new commit message.
For example, ``cherry-picked from commit 1e24c2671acdbcf81207c43da39e09846f404dc3``.
With a hash, tracking the original commit in a mainline/SoC vendor tree is easier.
24 changes: 12 additions & 12 deletions source/reference-manual/linux/factory-device-reset.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
Factory Reset
=============

In this context, factory reset means restoring the device to the original state.
This is a feature of LmP rather than FoundriesFactory.
Reset is performed as a script in ramdisk during boot.
It is triggered by presence of specific files.
In this context, Factory reset means restoring a device to the original state.
This is a feature of LmP, rather than of FoundriesFactory®.
A reset is performed as a script in ramdisk during boot.
It is triggered by the presence of specific files.
Presence of the files is specified in the following order:

#. ``/var/.factory_reset``
Expand All @@ -16,18 +16,18 @@ Presence of the files is specified in the following order:
Each file has specific meaning.
When a higher priority file is detected, remaining files are ignored.

Full factory reset
Full Factory Reset
------------------

When the file ``/var/.factory_reset`` is present, the script performs full reset.
Full reset means restoring contents of ``/etc/`` and ``/var/`` from :ref:`ostree<ref-static-deltas>`.
When the file ``/var/.factory_reset`` is present, the script performs a full reset.
A full reset means restoring contents of ``/etc/`` and ``/var/`` from :ref:`ostree<ref-static-deltas>`.
All contents created in these directories at runtime will be erased.

Partial factory reset
Partial Factory Reset
---------------------

There are currently two options in partial reset.
The main difference with full reset is that the device remains connected to the FoundriesFactory®.
The main difference with full reset is that the device remains connected to your Factory.

Keep SOTA
~~~~~~~~~
Expand All @@ -38,17 +38,17 @@ Contents of ``/var/`` are partially removed.
``/var/sota/`` contents are kept to allow aktualizr-lite to be preserved.
Docker images and compose apps are deleted.

Keep SOTA and docker
Keep SOTA and Docker
~~~~~~~~~~~~~~~~~~~~

When the file ``/var/.factory_reset_keep_sota_docker`` is present,
contents of ``/etc/`` are restored from ostree.
Contents of ``/var/`` are partially removed.
``/var/sota/`` contents are kept to allow aktualizr-lite and
compose-apps to be preserved.
``/var/lib/`` is preserved as the docker objects are stored there.
``/var/lib/`` is preserved as the Docker objects are stored there.

RPMB
~~~~

Currently ``RPMB`` is not cleared in either reset procedures.
Currently, ``RPMB`` is not cleared in either reset procedures.
Loading
Loading