new file mode 100644
@@ -0,0 +1,115 @@
+==================================
+meta-swupdate: building with Yocto
+==================================
+
+Overview
+========
+
+The Yocto-Project_ is a community project under the umbrella of the Linux
+Foundation that provides tools and template to create the own custom Linux-based
+software for embedded systems.
+
+.. _Yocto-Project: http://www.yoctoproject.org
+.. _meta-SWUpdate: https://github.com/sbabic/meta-swupdate.git
+
+Add-on features can be added using *layers*. meta-swupdate_ is the layer to
+cross-compile the SWUpdate application and to generate the compound SWU images
+containing the release of the product. As described in Yocto's documentation
+about layers, you should include it in your *bblayers.conf* file to use it.
+
+The swupdate class
+==================
+
+meta-swupdate contains a class specific for SWUpdate. It helps to generate the
+SWU image starting from images built inside the Yocto. It requires that all
+components, that means the artifacts that are part of the SWU image, are present
+in the Yocto's deploy directory. This class should be inherited by recipes
+generating the SWU. The class defines new variables, all of them have the prefix
+*SWUPDATE_* in the name.
+
+- **SWUPDATE_IMAGES** : this is a list of the artifacts to be packaged together.
+ The list contains the name of images without any extension for MACHINE or
+ filetype, that are added automatically.
+ Example :
+
+::
+
+ SWUPDATE_IMAGES = "core-image-full-cmdline uImage"
+
+- **SWUPDATE_IMAGES_FSTYPES** : extension of the artifact. Each artifact can
+ have multiple extension according to the IMAGE_FSTYPES variable.
+ For example, an image can be generated as tarball and as UBIFS for target.
+ Setting the variable for each artifact telles the class which file must
+ be packed into the SWU image.
+
+
+::
+
+ SWUPDATE_IMAGES_FSTYPES[core-image-full-cmdline] = ".ubifs"
+
+- **SWUPDATE_IMAGES_NOAPPEND_MACHINE** : flag to use drop the machine name from the
+ artifact file. Most images in *deploy* have the name of the Yocto's machine in the
+ filename. The class adds automatically the name of the MACHINE to the file, but some
+ artifacts can be deploes without it.
+
+::
+
+ SWUPDATE_IMAGES_NOAPPEND_MACHINE[my-image] = "1"
+
+- **SWUPDATE_SIGNING** : if set, the SWU is signed.
+- **SWUPDATE_SIGN_TOOL** : instead of using openssl, use SWUPDATE_SIGN_TOOL to sign
+ the image. A typical use case is together with a hardware key.
+- **SWUPDATE_PRIVATE_KEY** : this is the file with the private key used to sign the
+ image.
+- **SWUPDATE_PASSWORD_FILE** : an optional file containing the password for the private
+ key.
+
+Automatic sha256 in sw-description
+----------------------------------
+
+The swupdate class takes care of computing and inserting sha256 hashes in the
+sw-description file. The attribute *sha256* **must** be set in case the image
+is signed. Each artifact must have the attribute:
+
+::
+
+ sha256 = "@artifact-file-name@"
+
+For example, to add sha256 to the standard Yocto core-image-full-cmdline:
+
+::
+
+ sha256 = "@core-image-full-cmdline-machine.ubifs";
+
+
+The name of the file must be the same as in deploy directory.
+
+
+Template for recipe using the class
+-----------------------------------
+
+::
+
+ DESCRIPTION = "Example recipe generating SWU image"
+ SECTION = ""
+
+ LICENSE = ""
+
+ # Add all local files to be added to the SWU
+ # sw-description must always be in the list.
+ # You can extend with scripts or wahtever you need
+ SRC_URI = " \
+ file://sw-description \
+ "
+
+ # images to build before building swupdate image
+ IMAGE_DEPENDS = "core-image-full-cmdline virtual/kernel"
+
+ # images and files that will be included in the .swu image
+ SWUPDATE_IMAGES = "core-image-full-cmdline uImage"
+
+ # a deployable image can have multiple format, choose one
+ SWUPDATE_IMAGES_FSTYPES[core-image-full-cmdline] = ".ubifs"
+ SWUPDATE_IMAGES_FSTYPES[uImage] = ".bin"
+
+ inherit swupdate
@@ -32,6 +32,7 @@ SWUpdate Documentation
suricatta.rst
swupdate-ipc.rst
progress.rst
+ building-with-yocto.rst
############################################
Help and support
Add a section about building with Yocto and how to use the swupdate class to generate the SWU image. Signed-off-by: Stefano Babic <sbabic@denx.de> --- doc/source/building-with-yocto.rst | 115 +++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 2 files changed, 116 insertions(+) create mode 100644 doc/source/building-with-yocto.rst