Add more callbacks for fork() event, doc progress

* Add fork.prepare(), fork.parent() and fork.child() to match with
  pthread_atfork(), which makes more sense
* Code documentation progress

4 files changed, 110 insertions, 15 deletions

diff --git a/scripts/build-all.sh b/scripts/build-all.sh
index 038c124..61e749f 100755
--- a/scripts/build-all.sh
+++ b/scripts/build-all.sh
@@ -1,6 +1,15 @@
 #!/bin/bash
-set -e
+## \file
+# \brief Build all target arches specified and native tools necessary for
+#	fabrication of executables. You'll use this script a lot!
+# \note xcomp is required for this script to function.
+set -e # die on error
 
+##
+# \note \c ARCH_ARR, \c TOOLCHAIN_ARR and \c HOST_ARR form tuples of target
+# arches. \c ARCH_ARR lists the name of the arches to be used for the output
+# files(suffix). \c TOOLCHAIN_ARR lists the \b xcomp targets for each arch.
+# \c HOST_ARR is the list of the toolchain prefixes.
 ARCH_ARR=(
 #	"aarch64"
 	"armv4t"
@@ -37,6 +46,7 @@ HOST_ARR=(
 	"powerpc-linux"
 	"sh4-linux"
 )
+# Length check. All three arrays must have the same number of elements.
 ARR_SIZE="${#ARCH_ARR[@]}"
 if [ $ARR_SIZE -ne "${#TOOLCHAIN_ARR[@]}" ] ||
 	[ $ARR_SIZE -ne "${#HOST_ARR[@]}" ];
@@ -45,21 +55,37 @@ then
 	exit 2
 fi
 
+# The root prefix. Note that the script is run from the project root directory.
 PROONE_PREFIX="builds"
+# The prefix to debug symbol files
 PROONE_DEBUG_SYM_DIR="$PROONE_PREFIX/debug"
+# The prefix to Proone executables
 PROONE_EXEC_DIR="$PROONE_PREFIX/proone.bin"
+# The prefix to native tools
 PROONE_TOOLS_DIR="$PROONE_PREFIX/tools"
+# The prefix to miscellaneous executables for target
 PROONE_MISC_BIN_DIR="$PROONE_PREFIX/misc"
+# The name of the directory for release build Proone executables
 PROONE_REL_DIR="$PROONE_PREFIX/proone"
+# The prefix to debug symbol files
 export PROONE_DEBUG_SYM_PREFIX="$PROONE_DEBUG_SYM_DIR/"
+# The prefix to all stripped executables
 export PROONE_EXEC_PREFIX="$PROONE_EXEC_DIR/stripped"
+# The prefix to the original Proone executable output by the compiler
 export PROONE_ENTIRE_PREFIX="$PROONE_EXEC_DIR/entire"
+# The prefix to the disassembler output
 export PROONE_ASM_PREFIX="$PROONE_EXEC_DIR/asm"
+# The prefix to the readelf output
 export PROONE_READELF_PREFIX="$PROONE_EXEC_DIR/readelf"
+# The prefix to the miscellaneous executables
 export PROONE_MISC_BIN_PREFIX="$PROONE_MISC_BIN_DIR/"
+# The prefix to the names of the release build Proon executables
 PROONE_REL_PREFIX="$PROONE_REL_DIR/proone"
+# The path to the cred dict binary file
 PROONE_CDICT="$PROONE_PREFIX/cred_dict.bin"
+# The path to the dvault binary file
 PROONE_DVAULT="$PROONE_PREFIX/dvault.bin"
+# The array of the native tools
 PROONE_TOOLS="
 	proone-pack
 	proone-list-arch
@@ -68,7 +94,9 @@ PROONE_TOOLS="
 	proone-ipaddr-arr
 "
 
+################################################################################
 
+# Drop the root directory and set up the skeleton
 rm -rf "$PROONE_PREFIX"
 mkdir\
 	"$PROONE_PREFIX"\
@@ -77,27 +105,29 @@ mkdir\
 	"$PROONE_TOOLS_DIR"\
 	"$PROONE_MISC_BIN_DIR"\
 	"$PROONE_REL_DIR"
+# Ignore the clean up error because the project may not have been configured
 set +e
 make distclean
 set -e
 
-# native build for tools
+# Build native tools
 ./configure $PROONE_AM_CONF
 make -j$(nproc) -C src $PROONE_TOOLS
 for t in $PROONE_TOOLS; do
 	cp -a "src/$t" "$PROONE_TOOLS_DIR"
 done
+# Copy the test suites as well
 cp -a "./src/run-tests.sh" "./src/testlist" "$PROONE_MISC_BIN_DIR"
 make distclean
 
-# generate dvault
+# Generate dvault and cred dict binary
 "$PROONE_TOOLS_DIR/proone-mkcdict"\
 	"./src/proone_conf/cred_dict.txt"\
 	"$PROONE_CDICT"
 "$PROONE_TOOLS_DIR/proone-mkdvault" "$PROONE_CDICT" > "$PROONE_DVAULT"
 DVAULT_SIZE=$(stat -c "%s" "$PROONE_DVAULT")
 
-# cross-compile targets
+# Build all targets
 for (( i = 0; i < ARR_SIZE; i += 1 )); do
 	PROONE_BIN_OS="linux"\
 	PROONE_HOST="${HOST_ARR[$i]}"\
@@ -107,7 +137,7 @@ for (( i = 0; i < ARR_SIZE; i += 1 )); do
 		"scripts/build-arch.sh"
 done
 
-# pack
+# Do pack
 "$PROONE_TOOLS_DIR/proone-pack"\
 	"$PROONE_REL_PREFIX"\
 	"$PROONE_DVAULT"\
diff --git a/scripts/build-arch.sh b/scripts/build-arch.sh
index 9fc2ed0..3127850 100755
--- a/scripts/build-arch.sh
+++ b/scripts/build-arch.sh
@@ -1,17 +1,38 @@
 #!/bin/bash
+## \file
+# \brief Build one target. Usually, this script is run by build-all.sh although
+#	it can be run standalone by setting all the required environment variables
+#	by hand.
 set -e
 
+# Miscellaneous executables
 MISC_BIN="
 	proone-stress
 	proone-resolv
 	proone-test_proto
 	proone-test_util
 "
+# Proone executable output path
 BIN_PATH="$PROONE_EXEC_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
+# Unstripped Proone executable output path
 ENTIRE_BIN_PATH="$PROONE_ENTIRE_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
+# Path to readelf output of unstripped executable
 READELF_PATH="$PROONE_READELF_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
+# Disassembler output path (unused)
 ASM_PATH="$PROONE_ASM_PREFIX.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
 
+##
+# \brief Separate debug symbols from an executable
+# \param[in] 1 the input executable
+# \param[out] 2 the stripped executable for release build
+# \param[out] 3 the debug symbols
+# \param[out] 4 (optional)a copy of \p 1
+# \note This is a convenience function for creating various binary files from
+#	the compiler executable output. The two types of files, the stripped
+#	executable and the debug symbol, should be kept for each release in order to
+#	analyse core dumps.
+# \note When \p 4 is used, the function copies \p 1 to \p 4 and
+#	dumps the output of readelf to \c $READELF_PATH.
 separate_debug() {
 	cp -a "$1" "$2"
 	if [ ! -z "$4" ]; then
@@ -37,11 +58,13 @@ separate_debug() {
 	"$PROONE_HOST-objcopy" --add-gnu-debuglink="$3" "$2"
 }
 
+# do build
 ./configure --host="$PROONE_HOST" --enable-static $PROONE_AM_CONF
 cd src
 make -j$(nproc) proone.bin $MISC_BIN
 cd ..
 
+# extract output
 separate_debug\
 	src/proone.bin\
 	"$BIN_PATH"\
@@ -54,4 +77,5 @@ for b in $MISC_BIN; do
 		"$PROONE_DEBUG_SYM_PREFIX""$b.sym.$PROONE_BIN_OS.$PROONE_BIN_ARCH"
 done
 
+# clean up for the next arch build
 make distclean
diff --git a/scripts/do_symsize.sh b/scripts/do_symsize.sh
index 154fb00..990c0ba 100755
--- a/scripts/do_symsize.sh
+++ b/scripts/do_symsize.sh
@@ -1,25 +1,44 @@
 #!/bin/bash
+## \file
+# \brief Generate the text files of the symbol size table from the readelf
+#	output. The values are separated by white spaces. Only 3 fields are
+#	extracted in order: the size of symbol in decimal, the type of the symbol
+#	and the name of the symbol. The text files can be imported into spreadsheet
+#	or document files to make the tables a printable form.
+
+# The input prefix
 ELF_PREFIX='./builds/proone.bin/readelf'
+# The output prefix
 OUT_PREFIX='./builds/proone.bin/symsize'
+# The number of threads on the host
 NPROC=$(nproc)
+# The number of concurrent processes
 NB_PROC=0
 
-#
-# \param 1: input file
-# \param 2: output file
+##
+# \brief Call the script that actually does the job
+# \param 1 input file
+# \param 2 output file
 call_extsymsize () {
 	./scripts/extsymsize.sh < "$1" | sort -nr > "$2"
 }
 
+# Process each readelf output file
 for f in "$ELF_PREFIX".*; do
+	# Extract the arch from the file name
+	# The script assumes that the "middle name" is the name of the arch
 	suffix=$(echo "$f" | egrep -o '(\.\w+\.\w+)$')
 	if [ $? -ne 0 ]; then
 		echo "$f: invalid suffix" >&2
 		exit 1
 	fi
 
+	# Die on error: while running \c extsymsize.sh or in the process of
+	# launching it
 	set -e
 	out="$OUT_PREFIX""$suffix"
+	# Limit the number of processses running concurrently to the number of
+	# threads on the host.
 	if [ $NB_PROC -lt $NPROC ]; then
 		call_extsymsize "$f" "$out" &
 		let 'NB_PROC += 1'
@@ -30,6 +49,7 @@ for f in "$ELF_PREFIX".*; do
 	set +e
 done
 
+# Reap processes
 for (( i = 0; i < NB_PROC; i += 1 )); do
 	wait
 done
diff --git a/scripts/extsymsize.sh b/scripts/extsymsize.sh
index b73a216..d7f2572 100755
--- a/scripts/extsymsize.sh
+++ b/scripts/extsymsize.sh
@@ -1,5 +1,12 @@
 #!/bin/bash
+## \file
+# \brief Process the standard input to extract the desired fields from readelf
+#	output. Use \c do_symsize.sh to generate the tables for all targets.
+
+# The number of symbol tables. Should be 1 but multiple symbol tables may exist.
 NB_SYMTABS=0
+# The headers of the fields to extract in the order they should appear in the
+# output.
 declare -a FMT_HEADERS
 FMT_HEADERS=(
 	"size"
@@ -7,8 +14,12 @@ FMT_HEADERS=(
 	"name"
 )
 
-#
-# \param 1: re of the line to skip to
+##
+# \brief Skip to the line that matches the regular expression
+# \param 1 The regular expression of the line to skip to
+# \retval 0 if a line that mathces the regular expression has been processed and
+#	the pending standard input data is now the line that follows.
+# \retval 1 if no match has been found and the standard input has reached EOF.
 skip_to () {
 	while read l; do
 		if echo "$l" | egrep -q "$1"; then
@@ -18,15 +29,18 @@ skip_to () {
 	return 1
 }
 
-#
-# \param *: message
+##
+# \brief This is just like \c echo, except that it outputs to the standard
+#	error, not output.
 echo_err () {
 	echo $@ >&2
 }
 
-#
-# \param 1: (optional)message
-# \param 2: (optional)exit code
+##
+# \brief Exit with error code and message.
+# \param 1 (optional)The error message. No output is generated if empty string.
+# \param 2 (optional)The exit code. Must be a numeric value that's accepted by
+#	the OS. The default value 1 is used if empty string.
 die () {
 	local ec
 
@@ -41,15 +55,18 @@ die () {
 	exit $ec
 }
 
+# For each symbol table
 while skip_to "^[Ss]ymbol table '(\\.|\\w)+' contains [0-9]+ entries:\$"; do
 	unset idx_map name_map
 	declare -A idx_map name_map
 
+	# Read the header line
 	if ! read l; then
 		die "Unexpected EOF"
 	fi
 	let 'NB_SYMTABS += 1'
 
+	# Map the fields
 	i=0
 	for h in $l; do
 		h="${h,,}"
@@ -68,6 +85,7 @@ while skip_to "^[Ss]ymbol table '(\\.|\\w)+' contains [0-9]+ entries:\$"; do
 		let 'i += 1'
 	done
 
+	# Check if all the fields desired are there
 	for i in ${FMT_HEADERS[@]}; do
 		if [ -z ${idx_map["$i"]} ]; then
 			echo_err "Missing header in symbol table: ${FMT_HEADERS["$i"]}"
@@ -75,6 +93,8 @@ while skip_to "^[Ss]ymbol table '(\\.|\\w)+' contains [0-9]+ entries:\$"; do
 		fi
 	done
 
+	# For each entry line
+	# Assume that the table ends with an empty line
 	while read l && [ ! -z "$l" ]; do
 		unset size type name
 
@@ -96,6 +116,7 @@ while skip_to "^[Ss]ymbol table '(\\.|\\w)+' contains [0-9]+ entries:\$"; do
 	done
 done
 
+# Treat input data with no symbol table as error
 if [ $NB_SYMTABS -eq 0 ]; then
 	die "No symbol table found."
 fi