From 124778e478faa2168394451c0fb872e07707983e Mon Sep 17 00:00:00 2001 From: Fabian Hartung Date: Fri, 20 Jun 2025 11:23:28 +0200 Subject: [PATCH 1/2] Development: Update documentation for cross-compilation process Signed-off-by: Fabian Hartung --- docs/source/development.rst | 96 ++++++++++++++++++++++++++----------- 1 file changed, 67 insertions(+), 29 deletions(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index 7b76e45..f00f68b 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -7,14 +7,13 @@ Cross-compiling for Charge SOM ============================== -Another way to integrate custom applications into the firmware image is to cross-compile the application -for Charge SOM and include it in the image. A pre-requisite for this is to have the latest firmware image -as a developer build. Always keep in mind, if you want to build a new EVerest module it must be -compatible to the EVerest release within the firmware. Please have a look at the official -`EVerest documentation `_, -how to checkout a dedicated EVerest release. +Cross-compilation is the fastest and most convenient way to test your own modules directly on the target +system during development. The cross-compiled project can then either be transferred directly via FTP +to the charge controller or integrated into a firmware image and installed on the target using the `rauc` command. -#. On an Ubuntu or Debian-based Linux distribution, install the cross-compilers for Charge SOM. +The following steps describe how to cross-compile a module for the Charge SOM platform. + +#. On an Ubuntu or Debian-based Linux distribution, install the cross-compilers for Charge SOM: .. code-block:: console @@ -29,85 +28,124 @@ how to checkout a dedicated EVerest release. .. note:: Alternatively, if the above command does not work, you can use the following command: + .. code-block:: console unsquashfs -d bundle-staging .image - But this will not verify the signature of the firmware image. + However, this will not verify the signature of the firmware image. -#. Mount the ext4 root filesystem image as a loop device. +#. Mount the extracted ext4 root filesystem image as a loop device: .. code-block:: console sudo mkdir -p /mnt/rootfs sudo mount bundle-staging/core-image-minimal-chargesom.ext4 /mnt/rootfs -#. Create a new directory in the folder where the new module was created (my-module) and create a new - file called :code:`toolchain.cmake`. This file is used to set the toolchain for the cross-compilation. +#. Create a new directory in your `everest-workspace` directory (in parallel to the `everest-core` directory) and + create a new file named :code:`toolchain.cmake`: .. code-block:: console - cd my-module + cd everest-workspace mkdir toolchain cd toolchain touch toolchain.cmake - -#. Store the following lines in the :code:`toolchain.cmake` file: +#. Save the following content in the :code:`toolchain.cmake` file: .. literalinclude:: ../../includes/_static/files/toolchain.cmake -#. Create a new :code:`build` directory in "my-module" and navigate to it. +#. The resulting directory structure should look like this: .. code-block:: console - mkdir build - cd build + everest-workspace/ + |── {MyEVerestModule} + ├── everest-core + └── toolchain + └── toolchain.cmake -#. Run the following command inside to configure the build. +#. Create a new :code:`build_tarragon` directory in the EVerest project directory (e.g. within your own EVerest + module project directory or :code:`everest-core` if you want to build the everest-core modules): .. code-block:: console - cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain/toolchain.cmake -DCMAKE_SYSROOT=/mnt/rootfs .. + cd ../{MyEVerestModule} + mkdir build_tarragon + cd build_tarragon -#. When this ends successfully, start cross-compiling using :code:`make`: +#. Run the following command inside the `build_tarragon` directory to configure the build: + + .. code-block:: console + + cmake -DCMAKE_TOOLCHAIN_FILE=../../toolchain/toolchain.cmake -DCMAKE_SYSROOT=/mnt/rootfs .. + +#. When this completes successfully, start cross-compiling using :code:`make`: .. code-block:: console make install -j$(nproc) -#. Test that the resulting binaries are compiled for Charge SOM as a target: +#. If the build was successful, a dist directory will be created with the cross-compiled binaries and + the manifest files of the modules. Please check if the following directory structure was created: .. code-block:: console - file dist/libexec/everest/modules/MyModule/MyModule + dist/ + └── libexec + └── everest + └── modules + └── {MyEVerestModule} + ├── {MyEVerestModule} (binary) + └── {MyEVerestModule}.manifest (manifest file) + +#. Verify that the resulting binaries were compiled for the Charge SOM platform: + + .. code-block:: console + + file dist/libexec/everest/modules/{MyEVerestModule}/{MyEVerestModule} The output should be something like: .. code-block:: console - dist/libexec/everest/modules/MyModule/MyModule: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), + dist/libexec/everest/modules/{MyEVerestModule}/{MyEVerestModule}: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=ad2342fdd3b8fb1949fc3e13b77382d3da72f28a, for GNU/Linux 3.7.0, stripped -#. The resulting binary and manifest file can be copied to the previously mounted root filesystem. +#. The resulting binary and manifest can be found in the :code:`dist/libexec/everest/modules/{MyEVerestModule}` + directory. If you want to test the module on the target system, you can copy the module directory using + :code:`scp` or :code:`rsync`: + + .. code-block:: console + + scp -r dist/libexec/everest/modules/{MyEVerestModule} root@:/usr/libexec/everest/modules/ + +#. To include the new module in a firmware image, copy the module directory into the mounted root filesystem: .. code-block:: console - cp dist/libexec/everest/modules/MyModule /mnt/rootfs/usr/libexec/everest/modules/ + cp -r dist/libexec/everest/modules/{MyEVerestModule} /mnt/rootfs/usr/libexec/everest/modules/ -#. umount the loop device. +#. Unmount the loop device: .. code-block:: console sudo umount /mnt/rootfs -#. Make sure that the customized filesystem is in a clean state. +#. Ensure that the modified filesystem is in a clean state: .. code-block:: console fsck.ext4 -f bundle-staging/core-image-minimal-chargesom.ext4 -#. Follow the steps under the section :ref:`firmware_customization` to install your PKI certificate, pack - the modified root filesystem image again into the firmware update image, and test the new firmware image. +#. Follow the steps under the section :ref:`firmware_customization` to install your PKI certificate, repackage +the modified root filesystem into a firmware update image, and test the new firmware. + +.. _creating_fw_images: + +.. include:: ../../includes/development_creating_fw_images.inc + +.. _debugging_and_logging: .. include:: ../../includes/development_debugging_and_logging.inc From 63a984a942add6031f0008f0b9a0c92178affa49 Mon Sep 17 00:00:00 2001 From: Stefan Wahren Date: Mon, 23 Jun 2025 16:21:18 +0200 Subject: [PATCH 2/2] Development: Address review comments - fix file transfer protocol - adapt build directory to Charge SOM - fix manifest filename Signed-off-by: Stefan Wahren --- docs/source/development.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index f00f68b..e8fe505 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -8,7 +8,7 @@ Cross-compiling for Charge SOM ============================== Cross-compilation is the fastest and most convenient way to test your own modules directly on the target -system during development. The cross-compiled project can then either be transferred directly via FTP +system during development. The cross-compiled project can then either be transferred directly via SFTP to the charge controller or integrated into a firmware image and installed on the target using the `rauc` command. The following steps describe how to cross-compile a module for the Charge SOM platform. @@ -66,16 +66,16 @@ The following steps describe how to cross-compile a module for the Charge SOM pl └── toolchain └── toolchain.cmake -#. Create a new :code:`build_tarragon` directory in the EVerest project directory (e.g. within your own EVerest +#. Create a new :code:`build_csom` directory in the EVerest project directory (e.g. within your own EVerest module project directory or :code:`everest-core` if you want to build the everest-core modules): .. code-block:: console cd ../{MyEVerestModule} - mkdir build_tarragon - cd build_tarragon + mkdir build_csom + cd build_csom -#. Run the following command inside the `build_tarragon` directory to configure the build: +#. Run the following command inside the `build_csom` directory to configure the build: .. code-block:: console @@ -98,7 +98,7 @@ The following steps describe how to cross-compile a module for the Charge SOM pl └── modules └── {MyEVerestModule} ├── {MyEVerestModule} (binary) - └── {MyEVerestModule}.manifest (manifest file) + └── manifest.yaml (manifest file) #. Verify that the resulting binaries were compiled for the Charge SOM platform: