Improve docs for zeroize.c and test_zeroize.gdb

programs/test/zeroize.c

@@ -1,5 +1,14 @@
 /*
- *  Zeroize demonstration program
+ * Zeroize application for debugger-driven testing
+ *
+ * This is a simple test application used for debbuger-driven testing to check
+ * whether calls to mbedtls_zeroize() are being eliminated by compiler
+ * optimizations. This application is used by the GDB script at
+ * tests/scripts/test_zeroize.gdb under the assumption that line numbers do not
+ * change often (as opposed to the library code) because the script sets a
+ * breakpoint at the last return statement in the main() function of this
+ * program. The debugger facilities are then used to manually inspect the
+ * memory and verify that the call to mbedtls_zeroize() was not eliminated.
  *
  *  Copyright (C) 2017, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0

tests/scripts/test_zeroize.gdb

@@ -13,11 +13,36 @@
 # debugger manually checks the contents to be zeroized and checks that it is
 # actually cleared.
 #
+# The mbedtls_zeroize() test is debugger driven because there does not seem to
+# be a mechanism to reliably check whether the zeroize calls are being
+# eliminated by compiler optimizations from within the compiled program. The
+# problem is that a compiler would typically remove what it considers to be
+# "unecessary" assignments as part of redundant code elimination. To identify
+# such code, the compilar will create some form dependency graph between
+# reads and writes to variables (among other situations). It will then use this
+# data structure to remove redundant code that does not have an impact on the
+# program's observable behavior. In the case of mbedtls_zeroize(), an
+# intelligent compiler could determine that this function clears a block of
+# memory that is not accessed later in the program, so removing the call to
+# mbedtls_zeroize() does not have an observable behavior. However, inserting a
+# test after a call to mbedtls_zeroize() to check whether the block of
+# memory was correctly zeroed would force the compiler to not eliminate the
+# mbedtls_zeroize() call. If this does not occur, then the compiler potentially
+# has a bug.
+#
 # Note: This test requires that the test program is compiled with -g3.
+#
+# WARNING: There does not seem to be a mechanism in GDB scripts to set a
+# breakpoint at the end of a function (probably because there are a lot of
+# complications as function can have multiple exit points, etc). Therefore, it
+# was necessary to hard-code the line number of the breakpoint in the zeroize.c
+# test app. The assumption is that zeroize.c is a simple test app that does not
+# change often (as opposed to the actual library code), so the breakpoint line
+# number does not need to be updated often.
 
 set confirm off
 file ./programs/test/zeroize
-break zeroize.c:90
+break zeroize.c:99
 
 set args ./programs/test/zeroize.c
 run