Merge pull request #55 from chargebyte/everest/chargesom-revision-of-development-chapter

Everest/chargesom: Revision of development chapter

Author: lategoodbye

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 <https://everest.github.io/nightly/dev_tools/edm.html#setting-up-and-updating-a-workspace>`_,
-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 SFTP
+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 <shipped_firmware>.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_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
 
-      cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain/toolchain.cmake -DCMAKE_SYSROOT=/mnt/rootfs ..
+      cd ../{MyEVerestModule}
+      mkdir build_csom
+      cd build_csom
 
-#. When this ends successfully, start cross-compiling using :code:`make`:
+#. Run the following command inside the `build_csom` 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)
+                      └── manifest.yaml (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@<ip_address>:/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