[PATCH] document the helper scripts for generating *ent.h headers

[Mike Frysinger]

Signed-off-by: Mike Frysinger <vapier at gentoo.org>
---
 HACKING-scripts   |   58 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 errnoent.sh       |    4 +++
 linux/ioctlent.sh |    4 +++
 signalent.sh      |    4 +++
 syscallent.sh     |    4 +++
 5 files changed, 74 insertions(+), 0 deletions(-)
 create mode 100644 HACKING-scripts

diff --git a/HACKING-scripts b/HACKING-scripts
new file mode 100644
index 0000000..ae4fabc
--- /dev/null
+++ b/HACKING-scripts
@@ -0,0 +1,58 @@
+Each strace port relies heavily on port-specific headers:
+	- errnoent.h - map error number to error name like strerror()
+	- ioctlent.h - map ioctl number to symbolic define
+	- signalent.h - map signal number to signal name like strsignal()
+	- syscallent.h - map syscall number to name and function signature
+
+Since generating these headers from scratch (or even just updating them) can be
+a big pain, there are a few scripts to help automate the process.  Since each
+port organizes their kernel sources differently, there may be a specific script
+for your kernel.
+
+We will use the Linux kernel (2.6.20+) as an example below (the Blackfin
+architecture to be specific).  Hopefully, it'll be obvious how to swap out a
+different system or architecture as your circumstances apply.
+
+ksrc=/usr/src/linux
+asrc=$ksrc/arch/blackfin/include/asm
+
+To use the errnoent.sh script, give it all the headers that might contain
+appropriate errno values.  Excessive headers are not a problem.  The resulting
+output should be directly usable without modification.
+	sh ./errnoent.sh \
+		$ksrc/include/linux/*errno*.h \
+		$ksrc/include/asm-generic/*errno*.h \
+		$asrc/*errno*.h \
+		> errnoent.h
+
+To use the ioctlent.sh script, give it all the base include directories.  The
+script will crawl all the headers and try to discover appropriate ioctls.
+Unlike the other scripts, this one creates files for further processing.  This
+is because ioctls tend to have a lot of define indirection, and the ioctlent.h
+header needs to be fully expanded into numeric form and sorted properly.  So
+first we process all of the ioctls with the ioctlent.sh into ioctldefs.h and
+ioctls.h, and then we compile them into ioctlsort.c.  The resulting output,
+while directly usable, only contains definitions that match exactly the current
+kernel version that the script ran against.  That means older/newer ioctl
+defines that might be present in the existing ioctlent.h header will be lost if
+things are copied directly.  A little creative use of `diff` and manual merging
+should be used to produce the final ioctlent.h header.
+	sh ./linux/ioctlent.sh $ksrc/include $asrc
+	gcc -Wall -I. linux/ioctlsort.c -o ioctlsort
+	./ioctlsort > ioctlent.h
+
+To use the signalent.sh script, give it all the headers that might contain
+appropriate signal values.  Excessive headers are not a problem.  The resulting
+output should be directly usable without modification.
+	sh ./signalent.sh \
+		$asrc/signal.h \
+		> signalent.h
+
+To use the syscallent.sh script, give it the header with the list of your
+system call numbers.  The resulting output is useful as a template for creating
+a proper header as it can really only detect the system call number and its
+name.  It has no way of knowing the number of arguments or strace flags for
+decoding them (yet?).
+	sh ./syscallent.sh \
+		$asrc/unistd.h \
+		> syscallent.h
diff --git a/errnoent.sh b/errnoent.sh
index 3a39a01..51bcb30 100644
--- a/errnoent.sh
+++ b/errnoent.sh
@@ -26,6 +26,10 @@
 #
 #	$Id: errnoent.sh,v 1.1 1999/02/19 00:22:09 wichert Exp $
 
+#
+# For usage information, please see HACKING-scripts
+#
+
 awk '
 /^#define[ 	]+E[A-Z0-9_]+[ 	]+[0-9]+/ {
 	errno[$3] = $2
diff --git a/linux/ioctlent.sh b/linux/ioctlent.sh
index 395d668..634d3d9 100644
--- a/linux/ioctlent.sh
+++ b/linux/ioctlent.sh
@@ -28,6 +28,10 @@
 #	$Id: ioctlent.sh,v 1.14 2009/02/22 03:01:20 vda_linux Exp $
 #
 
+#
+# For usage information, please see HACKING-scripts
+#
+
 # Validate arg count.
 case $# in
 1)
diff --git a/signalent.sh b/signalent.sh
index a045bf9..7177990 100644
--- a/signalent.sh
+++ b/signalent.sh
@@ -26,6 +26,10 @@
 #
 #	$Id: signalent.sh,v 1.2 2008/04/19 14:18:23 ldv Exp $
 
+#
+# For usage information, please see HACKING-scripts
+#
+
 cat $* |
 	sed -n -e 's/\/\*.*\*\// /' -e 's/^#[ 	]*define[ 	][ 	]*SIG\([^_ 	]*\)[ 	][ 	]*\([0-9][0-9]*\)[ 	]*$/\1 \2/p' |
 	sort -k2n | uniq |
diff --git a/syscallent.sh b/syscallent.sh
index 455eb6c..1425943 100644
--- a/syscallent.sh
+++ b/syscallent.sh
@@ -26,6 +26,10 @@
 #
 #	$Id: syscallent.sh,v 1.4 2008/04/19 14:18:23 ldv Exp $
 
+#
+# For usage information, please see HACKING-scripts
+#
+
 cat ${1+"$@"} |
 	sed -n 's/^#[ 	]*define[ 	][ 	]*SYS_\([^ 	]*\)[ 	]*[^0-9]*\([0-9]*\).*$/\1 \2/p
 s/^#[ 	]*define[ 	][ 	]*__NR_\([^ 	]*\)[ 	]*[^0-9]*\([0-9]*\).*$/\1 \2/p
-- 
1.6.1.3