From e9c3541bad9b8b9b3b3215592205b4bba5900cf5 Mon Sep 17 00:00:00 2001
From: Giulio Benetti <giulio.benetti@benettiengineering.com>
Date: Mon, 8 Nov 2021 20:51:30 +0100
Subject: [PATCH] docs/manual: add genimage.cfg file coding style standard
This patch adds the explanation for the genimage.cfg files coding standard.
A real standard is not defined upstream by the genimage utility
developers[1], but I try to give one here in Buildroot for consistency.
[1]: https://github.com/pengutronix/genimage
Signed-off-by: Giulio Benetti <giulio.benetti@benettiengineering.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
docs/manual/writing-rules.txt | 62 +++++++++++++++++++++++++++++++++++
1 file changed, 62 insertions(+)
diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt
index 3b809d5c48..28cb0fe4f1 100644
--- a/docs/manual/writing-rules.txt
+++ b/docs/manual/writing-rules.txt
@@ -136,6 +136,68 @@ LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
endif
---------------------
+[[writing-genimage-cfg]]
+
+=== The +genimage.cfg+ file
+
++genimage.cfg+ files contain the output image layout that genimage utility
+uses to create final .img file.
+
+An example follows:
+
+---------------------
+image efi-part.vfat {
+ vfat {
+ file EFI {
+ image = "efi-part/EFI"
+ }
+
+ file Image {
+ image = "Image"
+ }
+ }
+
+ size = 32M
+}
+
+image sdimage.img {
+ hdimage {
+ }
+
+ partition u-boot {
+ image = "efi-part.vfat"
+ offset = 8K
+ }
+
+ partition root {
+ image = "rootfs.ext2"
+ size = 512M
+ }
+}
+---------------------
+
+* Every +section+(i.e. hdimage, vfat etc.), +partition+ must be indented
+ with one tab.
+
+* Every +file+ or other +subnode+ must be indented with two tabs.
+
+* Every node(+section+, +partition+, +file+, +subnode+) must have an open
+ curly bracket on the same line of the node's name, while the closing one
+ must be on a newline and after it a newline must be added except for the
+ last one node. Same goes for its option, for example option +size = +.
+
+* Every +option+(i.e. +image+, +offset+, +size+) must have the +=+
+ assignment one space from it and one space from the value specified.
+
+* Filename must at least begin with genimage prefix and have the .cfg
+ extension to be easy to recognize.
+
+The +genimage.cfg+ files are the input for the genimage tool used in
+Buildroot to generate the final image file(i.e. sdcard.img). For further
+details about the _genimage_ language, refer to
+https://github.com/pengutronix/genimage/blob/master/README.rst[].
+
+
=== The documentation
The documentation uses the