Revise README.rst

README.rst

@@ -12,38 +12,27 @@
 
 |MIT| |Matrix|
 
-The meta-rauc layer provides support for integrating the RAUC update tool
-into your device.
+The meta-rauc Yocto/OpenEmbedded layer provides integration for
+`RAUC <https://github.com/rauc/rauc>`_, a robust and secure **update framework
+for embedded Linux systems**.
+
+This layer integrates RAUC into Yocto builds for both **target usage (update
+client)** and **host usage (bundle creation)**.
 
-Please see the corresponding sections below for more information.
 For a detailed description on steps necessary to integrate RAUC into your
 project, refer https://rauc.readthedocs.io/en/latest/integration.html.
 
 
-Dependencies
-============
-
-This layer depends on::
-
-  URI: https://github.com/openembedded/bitbake.git
-  branch: master
-
-  URI: https://github.com/openembedded/openembedded-core.git
-  layers: meta
-  branch: master
+Layer Dependencies
+==================
 
-For fuse-support in casync (the default)::
+This layer depends on:
 
-  URI: https://github.com/openembedded/meta-openembedded.git
-  layers: meta-filesystems
-  branch: master
+* `openembedded-core <https://github.com/openembedded/openembedded-core.git>`_
 
-Patches
-=======
+To use the optional casync feature with FUSE, you will also need:
 
-Please submit patches via GitHub pull request on https://github.com/rauc/meta-rauc
-
-Maintainer: Enrico Joerns <ejo@pengutronix.de>
+* ``meta-filesystems`` from `meta-openembedded <https://github.com/openembedded/meta-openembedded.git>`_.
 
 Migration Notes
 ===============
@@ -58,62 +47,44 @@ configuration-specific adaptions from your ``rauc_%.bbappend`` to a
 ``rauc-conf.bbappend`` file.
 
 
-I. Adding the rauc Layer to Your Build
-======================================
-
-In order to use this layer, you need to make the build system aware of
-it.
-
-Assuming the rauc layer exists at the top-level of your
-yocto build tree, you can add it to the build system by adding the
-location of the rauc layer to bblayers.conf, along with any
-other layers needed. e.g.::
-
-  BBLAYERS ?= " \
-    /path/to/yocto/meta \
-    /path/to/yocto/meta-poky \
-    /path/to/yocto/meta-yocto-bsp \
-    /path/to/yocto/meta-rauc \
-    "
-
+Adding the RAUC Update Service to Your Device
+=============================================
 
-II. Building and Using RAUC Host Tool
-=====================================
+To prepare your device for using RAUC as its update handler,
+at least the following steps are required:
 
-If you intend to build and use RAUC as a host tool from your BSP, e.g. for
-calling ``rauc info`` on your built bundle, simply run::
+1. Add ``rauc`` to ``DISTRO_FEATURES`` in your distro (or local) config::
 
-  bitbake rauc-native -caddto_recipe_sysroot
-  oe-run-native rauc-native rauc info --keyring=/path/to/keyring.pem tmp/deploy/images/<machine>/<bundle-name>.raucb
+     DISTRO_FEATURES += "rauc"
 
-If you need to execute the ``casync`` host tool manually, you can do this by running::
+2. Provide a RAUC system configuration (and keyring) in your BSP layer by
+   creating a ``rauc-conf.bbappend`` that fetches your custom ``system.conf``
+   (and keyring) from your layer::
 
-  bitbake casync-native -caddto_recipe_sysroot
-  oe-run-native casync-native casync --help
+     FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
 
-III. Adding the RAUC Update Service to Your Device
-==================================================
+   The ``rauc-conf`` recipe will install these files into ``/etc/rauc/`` by
+   default.
 
-To prepare your device for using RAUC as its update handler,
-you have to follow at least the following steps:
+   For information on how to write a proper RAUC system configuration, please
+   refer to the RAUC user documentation [1]_.
 
-1. Add `rauc` to `DISTRO_FEATURES` in your distro (or local) config::
+Note: If you do not use packagegroup-base, you also need to manually add
+the ``rauc`` package to your systems image recipe::
 
-     DISTRO_FEATURES += "rauc"
-
-2. Add a ``rauc-conf.bbappend`` in your device-specific (BSP) layer
-   that installs your RAUC system configuration file under
-   ``/etc/rauc/system.conf``. For information on how to write the RAUC
-   update file, please refer to the RAUC user documentation [1]_::
+     IMAGE_INSTALL:append = " rauc"
 
-     FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
+Building a RAUC Update Bundle
+=============================
 
-3. Create a bundle recipe for your device by adding a recipe
-   that inherits the `bundle` class and adds all desired
+1. Create a bundle recipe for your device by adding a recipe
+   that inherits the ``bundle`` class and adds all desired
    configuration::
 
      inherit bundle
 
+     RAUC_BUNDLE_FORMAT = "verity"
+
      RAUC_BUNDLE_SLOTS = "rootfs"
      RAUC_SLOT_rootfs = "my-rootfs-recipe"
 
@@ -126,18 +97,27 @@ you have to follow at least the following steps:
    For a more detailed explanation on the required and available variables,
    read the notes in the bundle.bbclass file.
 
-4. Build a bundle and the rootfs for your device::
+2. Build a bundle and the rootfs for your device::
 
      bitbake my-bundle-recipe
 
-Note: If you do not use packagegroup-base, you als need to manually add
-the `rauc` package to your systems image recipe::
 
-     IMAGE_INSTALL:append = " rauc"
+Building and Using the RAUC Host Tool
+=====================================
 
+To manually build and use RAUC as a host tool from your BSP (e.g. for
+calling ``rauc info`` on your built bundle), run::
 
-IV. Building The RAUC hawkBit Clients
-=====================================
+  bitbake rauc-native -caddto_recipe_sysroot
+  oe-run-native rauc-native rauc info --keyring=/path/to/keyring.pem tmp/deploy/images/<machine>/<bundle-name>.raucb
+
+To manually build and use the ``casync`` host tool, run::
+
+  bitbake casync-native -caddto_recipe_sysroot
+  oe-run-native casync-native casync --help
+
+Building The RAUC hawkBit Client
+================================
 
 This layer offers support for ``rauc-hawkbit-updater``, a daemon that
 interfaces between RAUC and the hawkBit deployment server.
@@ -146,19 +126,19 @@ To use ``rauc-hawkbit-updater`` in your system add to your image recipe::
 
     IMAGE_INSTALL:append = " rauc-hawkbit-updater"
 
-V. Configure Custom Kernel
-==========================
+Configure Custom Kernel
+=======================
 
-In order to use RAUC on your system, the kernel must support SquashFS and loop
+To use RAUC on your system, the kernel must support SquashFS and loop
 mounts. For the standard yocto kernel, the meta-rauc layer provides a kernel
 configuration fragment that enables the config options required for this.
 
 If you build your own kernel with a full custom ``defconfig`` file, you have to
 make sure that the options in ``recipes-kernel/linux/linux-yocto/rauc.cfg`` are
 enabled in your configuration, too.
 
-VI. Build RAUC Development Version
-==================================
+Build RAUC Development Version
+==============================
 
 Beside the standard release version recipes, the _git variants of RAUC recipes
 allow to build RAUC from a master branch revision that is newer than the latest
@@ -175,13 +155,21 @@ in your local.conf. Note that this has the same effect as setting
 ``DEFAULT_PREFERENCE = "1"`` for each recipe (target/native/nativesdk)
 individually.
 
-VII. Contributing
-=================
+Release Cycle
+=============
+
+We follow the Yocto Project release methodology, schedule, and stable/LTS
+support timelines.
+See https://docs.yoctoproject.org/ref-manual/release-process.html for more
+information.
+
+Contributing
+============
 
 To report bugs, file a new `issue <https://github.com/rauc/meta-rauc/issues>`_
 on GitHub.
 
-For fixing bugs, bumping recipes or adding new features, open a `pull request
+For fixing bugs, bumping recipes, or adding new features, open a `pull request
 <https://github.com/rauc/meta-rauc/pulls>`_ on GitHub.
 
 Add a ``Signed-off-by`` line to your commits according to the
@@ -191,23 +179,28 @@ Add a ``Signed-off-by`` line to your commits according to the
 Backporting
 -----------
 
-For backporting changes to a stable or LTS branch, two options exist:
+For backporting fixes or version bumps to a stable or LTS branch, two options exist:
 
 a) drop a backport request in the original pull request
 b) backport on your own and create a new pull request
 
-When doing backports on your own, make sure to include a cherry-pick note and
+When doing backports on your own, make sure to include a cherry-pick/backport note and
 the original commit-ish in a line below the original Signed-off-by and add your
 own Signed-off-by below.
 When using git, this can be done automatically with::
 
   git cherry-pick -xs <commit-ish>
 
-Note that backports will be accepted for actively maintained `poky releases
+Note that backports will be accepted for `actively maintained Yocto releases
 <https://wiki.yoctoproject.org/wiki/Releases>`_ only!
 
-VIII. References
-================
+Maintainer(s)
+-------------
+
+* Enrico Joerns <ejo@pengutronix.de>
+
+References
+==========
 
 .. [1] http://rauc.readthedocs.io/en/latest/