Add some documentation

Signed-off-by: Michael Buesch <mb@bu3sch.de>

diff --git a/debug/README b/debug/README
index 5ddd1021d31adab9f3c025eafd9dca3b01cb596a..08a6996996e63e5c31a6e707ea6001745c073af0 100644 (file)
--- a/debug/README
+++ b/debug/README
@@ -4,7 +4,44 @@ Note that it is licensed under the GNU GPL version 3 ONLY!
 Installing:
        Run the install.py script as root.
 
-Please be careful when using these tools. They have direct access to the
-hardware, so you can easily crash something.
+*******************************************************************************
+*  b43-fwdump                                                                 *
+*******************************************************************************
+
+b43-fwdump is an utility for dumping the current status of the device firmware
+on a running device. It has some auto-detection mechanisms. So if you have
+only one card in the machine, it will dump the firmware state of that card, if
+called without any parameters.
+Use the --shm option, if you want a Shared Memory dump.
+Use the --binary option, if you want b43-fwdump to automatically dump the
+disassembled code at the current PC. This is convenient for debugging
+firmware crashes.
+
+Note that b43-fwdump _must_ be run as root, as it needs direct access to the
+hardware through debugfs.
+Debugfs must be mounted and you must have a recent driver with support for raw
+hardware access through debugfs.
+If you get error messages about missing debugfs files, make sure to upgrade to
+the latest development snapshot of the b43 driver.
+
+*******************************************************************************
+*  b43-beautifier                                                             *
+*******************************************************************************
+
+b43-beautifier is a tool to replace constant expressions in raw disassembled
+firmware code with human-readable #defined names.
+
+The tool requires either the disassembled source code or a binary (which it
+will disassemble then) to start with. See the --asmfile and --binfile
+parameters.
+It also requires a path to the directory containing the hardware definitions.
+This is the "common" subdirectory found in the b43-ucode GIT repository.
+See the --defs parameter.
+
+
+
+
+Please be careful when using these tools. Some of them have direct access to
+the hardware, so you can easily crash something.
 
        Michael

diff --git a/debug/patcher-template b/debug/patcher-template
new file mode 100755 (executable)
index 0000000..a646ff8
--- /dev/null
+++ b/debug/patcher-template
@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+"""
+#  Copyright (C) 2008 Michael Buesch <mb@bu3sch.de>
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License version 3
+#  as published by the Free Software Foundation.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+import sys
+from libb43 import *
+
+
+if len(sys.argv) != 3 and len(sys.argv) != 2:
+       print "Usage: %s INPUT_FILE [OUTPUT_FILE]" % sys.argv[0]
+       sys.exit(1)
+
+infile = sys.argv[1]
+outfile = None
+if len(sys.argv) == 3:
+       outfile = sys.argv[2]
+
+try:
+
+       asm = Disassembler(file(infile).read(), "").getAsm()
+       p = TextPatcher(asm, "c053515533b60977d212fbcfa4fc2546") # TODO adjust the MD5SUM
+
+       # TODO
+       # Use p.addText() and p.delLine() for modifying the code
+
+       if outfile:
+               bin = Assembler(p.getText(), "--psize").getBinary()
+               file(outfile, "w").write(bin)
+       else:
+               sys.stdout.write(p.getText())
+
+except B43Exception:
+       print "Could not patch. Do you use the correct input file?"
+       sys.exit(1)