Merge branch 'release-1.0'

ChangeLog

@@ -1,3 +1,12 @@
+2022-07-08  André Colomb  <[email protected]>
+
+	* Add facility to implement custom post-processors on the output
+	image data, with the ability to further modify contained fields.
+	* Implement an example post-processor to calculate and store a CRC
+	checksum over the binary data.
+
+	* Release version 1.0
+
 2021-11-15  André Colomb  <[email protected]>
 
 	* Update pointers to available libelf implementations.

README.md

@@ -73,6 +73,7 @@ storage layout, and written back to an image file ready for flashing.
 	- Copying data from input to output image
 	- Overriding the symbol data size in case the ELF file reports a
       wrong value (such as with flexible array member in C structs)
+  * Post-processing steps to apply application-specific content rules
 
 
 Installation
@@ -122,9 +123,12 @@ for the `configure` script are:
   application specific command line options
 * `--enable-custom-fields`: Include code module providing descriptions
   of known application specific symbols with advanced processing.
+* `--enable-custom-post-process`: Include code module providing
+  post-processing functions to make further finalizing modifications
+  to an image.
 
 See the section "Application Extensions" below for more information on
-the latter two.  For more options, refer to the output of `./configure
+the latter.  For more options, refer to the output of `./configure
 --help`.  After configuration, the package can be built with `make
 all` and installed with `make install` (with sufficient file
 permissions).
@@ -441,14 +445,15 @@ application with special needs, the code can be easily extended to
 provide additional semantics or shortcut options supplementing the
 basic program logic.
 
-Two source code files are provided to showcase the possible
+Three source code files are provided to showcase the possible
 flexibility.  They will not be compiled by default and must first be
-enabled with the `configure` script switches `--enable-custom-fields`
-and `--enable-custom-options`, respectively. The sources are shipped
-within the distribution as:
+enabled with the `configure` script switches `--enable-custom-fields`,
+`--enable-custom-options` and `--enable-custom-post-process`,
+respectively. The sources are shipped within the distribution as:
 
 	src/custom_known_fields.c
 	src/custom_options.c
+	src/custom_post_process.c
 
 It is recommended to modify and adapt these files to the needs of the
 respective application.  To ease later upgrades and track changes in
@@ -525,6 +530,33 @@ option, but without plausibility checks and without the convenience of
 a human-readable number representation.
 
 
+### Adding Post-Processing Functions ###
+
+Post-processors in *elf-mangle* allow arbitrary validation and
+adjustment steps to be carried out on the output binary image.  They
+have access to the complete blob data, as well as the list of
+contained fields, with all layout transformations and overrides
+already applied.  Any changes made in a post-processor will affect
+what is written to the output image file and also pretty-printed on
+request.
+
+To use this, a function named `get_custom_post_processors()` should be
+provided in `custom_post_process.c`, returning a `NULL`-terminated
+list of `post_process_f` function pointers.  These functions will be
+called in the listed order, each with the resulting blob from the
+previous one.  The first `NULL` value in the list will stop
+post-processing, so optionally suppressing further steps can easily be
+facilitated by clearing an entry in the list.
+
+A possible application, as provided in the example implementation,
+handles a special field within the symbol maps to hold a checksum of
+the data for verification.  The stored CRC value should match the
+checksum calculated over the whole blob data, except for the checksum
+field itself.  The example showcases both a verification and an update
+step to adjust the checksum field, resulting in an image which
+includes basic error detection against data corruption.
+
+
 Examples
 --------
 

configure.ac

@@ -17,7 +17,7 @@
 # <http://www.gnu.org/licenses/>.
 
 
-AC_INIT([elf-mangle], [0.6.2], [[email protected]])
+AC_INIT([elf-mangle],[1.0],[[email protected]])
 AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_SRCDIR([src/elf-mangle.c])
 AC_CONFIG_AUX_DIR([.])
@@ -26,7 +26,7 @@ AM_INIT_AUTOMAKE([foreign -Wall -Werror])
 
 # Checks for programs.
 AC_USE_SYSTEM_EXTENSIONS
-AC_PROG_CC_C99
+AC_PROG_CC
 
 # Use GNU Gnulib if required macros are present
 m4_ifdef([gl_EARLY],
@@ -170,6 +170,20 @@ AC_MSG_RESULT([${custom_fields}])
 AM_CONDITIONAL([CUSTOM_FIELDS], [test "x$custom_fields" = xyes])
 
 
+AC_MSG_CHECKING([whether extension module for custom post-processors should be built])
+AC_ARG_ENABLE([custom-post-process],
+   [AS_HELP_STRING([--enable-custom-post-process],
+       [Build extension module with custom post-processors])],
+   [AS_CASE([$enableval],
+       [yes], [custom_post_process=yes],
+       [no],  [custom_post_process=no],
+       [AC_MSG_ERROR([bad value ${enableval} for --enable-custom-post-process])])
+   ],
+   [custom_post_process=no])
+AC_MSG_RESULT([${custom_post_process}])
+AM_CONDITIONAL([CUSTOM_POST_PROCESS], [test "x$custom_post_process" = xyes])
+
+
 # Ouput definitions
 AC_CONFIG_HEADERS([config.h])
 AC_CONFIG_FILES([Makefile Doxyfile src/Makefile po/Makefile.in])

gnulib/.gitignore

@@ -1,10 +1,9 @@
 /.deps
 /Makefile.am
-/_Noreturn.h
 /alloca.c
 /alloca.h
 /alloca.in.h
-/arg-nonnull.h
+/argp.h
 /argp-ba.c
 /argp-eexst.c
 /argp-fmtstream.c
@@ -17,27 +16,28 @@
 /argp-pv.c
 /argp-pvh.c
 /argp-xinl.c
-/argp.h
+/arg-nonnull.h
 /asnprintf.c
+/attribute.h
 /basename-lgpl.c
+/basename-lgpl.h
 /c++defs.h
-/dirname-lgpl.c
-/dirname.h
-/dosname.h
 /errno.in.h
-/float+.h
+/filename.h
 /float.c
 /float.in.h
+/float+.h
+/free.c
+/getopt.c
+/getopt.h
+/getopt.in.h
+/getopt1.c
 /getopt-cdefs.h
 /getopt-cdefs.in.h
 /getopt-core.h
 /getopt-ext.h
 /getopt-pfx-core.h
 /getopt-pfx-ext.h
-/getopt.c
-/getopt.h
-/getopt.in.h
-/getopt1.c
 /getopt_int.h
 /getsubopt.c
 /gettext.h
@@ -65,25 +65,26 @@
 /stdint.in.h
 /stdio.h
 /stdio.in.h
+/stdio-read.c
+/stdio-write.c
 /stdlib.h
 /stdlib.in.h
 /strcasecmp.c
 /strchrnul.c
 /strchrnul.valgrind
+/strerror.c
 /strerror-override.c
 /strerror-override.h
 /string.h
-/strerror.c
 /string.in.h
 /strings.h
 /strings.in.h
-/stripslash.c
 /strncasecmp.c
 /strndup.c
 /strnlen.c
+/sysexits.in.h
 /sys/types.h
 /sys_types.in.h
-/sysexits.in.h
 /unistd.c
 /unistd.h
 /unistd.in.h
@@ -94,5 +95,7 @@
 /warn-on-use.h
 /wchar.h
 /wchar.in.h
+/xalloc-oversized.h
 /xsize.c
 /xsize.h
+/_Noreturn.h

m4/.gitignore

@@ -3,45 +3,45 @@
 /alloca.m4
 /argp.m4
 /codeset.m4
-/dirname.m4
 /double-slash-root.m4
 /errno_h.m4
 /exponentd.m4
 /extensions.m4
 /extern-inline.m4
 /fcntl-o.m4
 /float_h.m4
+/free.m4
 /getopt.m4
 /getsubopt.m4
 /gettext.m4
-/glibc21.m4
 /glibc2.m4
+/glibc21.m4
 /gnulib-common.m4
 /gnulib-comp.m4
 /gnulib-tool.m4
 /iconv.m4
 /include_next.m4
 /intdiv0.m4
-/intldir.m4
 /intl.m4
+/intldir.m4
 /intlmacosx.m4
 /intmax.m4
 /intmax_t.m4
 /inttypes.m4
-/inttypes_h.m4
 /inttypes-pri.m4
+/inttypes_h.m4
 /lcmessage.m4
+/libtool.m4
 /lib-ld.m4
 /lib-link.m4
 /lib-prefix.m4
-/libtool.m4
+/limits-h.m4
 /lock.m4
+/longlong.m4
+/lt~obsolete.m4
 /ltoptions.m4
 /ltsugar.m4
 /ltversion.m4
-/lt~obsolete.m4
-/limits-h.m4
-/longlong.m4
 /malloc.m4
 /math_h.m4
 /memchr.m4
@@ -51,6 +51,7 @@
 /nls.m4
 /nocrash.m4
 /off_t.m4
+/pid_t.m4
 /po.m4
 /printf.m4
 /printf-posix.m4
@@ -66,19 +67,21 @@
 /stdint_h.m4
 /stdio_h.m4
 /stdlib_h.m4
+/std-gnu11.m4
 /strcase.m4
 /strchrnul.m4
 /strerror.m4
-/string_h.m4
 /strings_h.m4
+/string_h.m4
 /strndup.m4
 /strnlen.m4
+/sysexits.m4
 /sys_socket_h.m4
 /sys_types_h.m4
 /threadlib.m4
 /uintmax_t.m4
-/sysexits.m4
 /unistd_h.m4
+/vararrays.m4
 /vasnprintf.m4
 /visibility.m4
 /vsnprintf.m4

m4/gnulib-cache.m4

@@ -1,8 +1,8 @@
-# Copyright (C) 2002-2020 Free Software Foundation, Inc.
+# Copyright (C) 2002-2022 Free Software Foundation, Inc.
 #
 # This file is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
+# the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 #
 # This file is distributed in the hope that it will be useful,

po/POTFILES.in

@@ -1,6 +1,7 @@
 # List of source files which contain translatable strings.
 src/custom_known_fields.c
 src/custom_options.c
+src/custom_post_process.c
 src/field_print.c
 src/find_string.c
 src/image_formats.c
@@ -12,6 +13,7 @@ src/nvm_field.c
 src/options_elf-mangle.c
 src/options_lpstrings.c
 src/override.c
+src/post_process.c
 src/print_symbols.c
 src/symbol_map.c
 src/transform.c