HACKING-scripts: new doc file by Mike Frysinger

diff --git a/HACKING-scripts b/HACKING-scripts
new file mode 100644 (file)
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