[PATCH 4/9] create-diff-object: document kpatch_regenerate_special_section() behavior

[Roger Pau Monne <roger.pau@xxxxxxxxxx>]

The purpose of kpatch_regenerate_special_section() is fairly opaque without
spending a good amount of time and having quite a lot of knowledge about what
the special sections contains.

Introduce some comments in order to give context and describe the expected
functionality.

Signed-off-by: Roger Pau Monné <roger.pau@xxxxxxxxxx>
---
 create-diff-object.c | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/create-diff-object.c b/create-diff-object.c
index d8a2afbf2774..6a751bf3b789 100644
--- a/create-diff-object.c
+++ b/create-diff-object.c
@@ -1210,6 +1210,12 @@ static void kpatch_regenerate_special_section(struct 
kpatch_elf *kelf,
 
        src_offset = 0;
        dest_offset = 0;
+
+       /*
+        * Special sections processed here are array objects, hence in order to
+        * detect whether a special section needs processing attempt to get the
+        * element size.  Returning a size of 0 means no processing required.
+        */
        group_size = special->group_size(kelf, src_offset);
        if (group_size == 0) {
                log_normal("Skipping regeneration of a special section: %s\n",
@@ -1246,6 +1252,33 @@ static void kpatch_regenerate_special_section(struct 
kpatch_elf *kelf,
                if (src_offset + group_size > sec->base->sh.sh_size)
                        group_size = sec->base->sh.sh_size - src_offset;
 
+               /*
+                * Special sections handled perform a bunch of different tasks,
+                * but they all have something in common: they are array like
+                * sections that reference functions in the object file being
+                * processed.
+                *
+                * .bug_frames.* relocations reference the symbol (plus offset)
+                * where the exception is triggered from.
+                *
+                * .altinstructions relocations contain references to
+                * coordinates where the alternatives are to be applied, plus
+                * coordinates that point to the replacement code in
+                * .altinstr_replacement.
+                *
+                * .ex_table relocations contain references to the coordinates
+                * where the fixup code should be executed, plus relocation
+                * coordinates that point to the text code to execte living in
+                * the .fixup section.
+                *
+                * .livepatch.hooks.* relocations point to the hook
+                * functions.
+                *
+                * Such dependencies allow to make a decision on whether an
+                * element in the array needs including in the livepatch: if
+                * the symbol pointed by the relocation is new or has changed
+                * the array element needs including.
+                */
                include = should_keep_rela_group(sec, src_offset, group_size);
 
                if (!include)
-- 
2.44.0