HACKING-scripts: new doc file by Mike Frysinger
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