fix bugs in pragma.py, add license/readme

3 files changed, 69 insertions, 25 deletions

diff --git a/tools/pragma/LICENSE b/tools/pragma/LICENSE
new file mode 100644
index 0000000..3b8d049
--- /dev/null
+++ b/tools/pragma/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Max Parisi https://github.com/mparisi20
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/tools/pragma/README.md b/tools/pragma/README.md
new file mode 100644
index 0000000..2f9074c
--- /dev/null
+++ b/tools/pragma/README.md
@@ -0,0 +1,35 @@
+# pragma.py
+#### Pragma processor for GameCube/Wii decompilation projects
+###### by Max Parisi
+
+This is a custom pragma processor meant for use with matching decompilation projects for GameCube and Wii games. It currently adds support for `#pragma regswap`.
+
+If some reconstructed C/C++ source code compiles to object binary whose only differences with a target binary are misallocated registers, you can use `#pragma regswap` 
+to correct the register allocation. This is an alternative to the strategy of inlining the desired assembly that aims to be more compact, self-documenting, and convenient. 
+
+`pragma.py` will compile your source code, then fix the regswaps by patching the range of the object file specified in each pragma invocation.
+
+## Usage
+Invoke `#pragma regswap` one or more times in a C or C++ source file with the following parameters:
+```
+#pragma regswap start end regA regB startFile
+```
+
+where, 
+* `start` - absolute address of start of affected region in hexadecimal format
+* `end` - absolute address of end of affected region (in hex)
+* `regA` - register to be swapped with `regB` (r0-r31 or f0-f31)
+* `regB` - register to swapped with `regA` (r0-r31 or f0-f31)
+* `startFile` - absolute address of the first function provided by this file (in hex)
+
+
+
+Then, invoke the pragma processor with the `-fix-regswaps` option:
+```
+python3 pragma.py [-h] [-fix-regswaps] cc cflags output source
+```
+
+
+## Future Work
+* Add support for an instruction-swap pragma (`#pragma iswap ...`)
+* Support for more architectures besides Gekko/Broadway PowerPC
diff --git a/tools/pragma/pragma.py b/tools/pragma/pragma.py
index 61d52de..f721c65 100644
--- a/tools/pragma/pragma.py
+++ b/tools/pragma/pragma.py
@@ -1,29 +1,18 @@
-"""
-
-./tools/pragma/pragma.py "$(CFLAGS)" -fix-regswaps
-
-#pragma regswap start end regA regB startFile
-
-pragma is only meaningful when you're trying to build a matching ROM.
-Modders don't care about regswaps. They care about shiftability.
-Modding projects must ignore #pragma regswap to avoid corrupting the ROM
-(add a Makefile option, "make mod" or similar)
-
-makefile executes...
-$(CC) $(CFLAGS) -lang c++ -c -o $@ $<
-
-$(PYTHON) $(PRAGMA) $(CC) "$(CFLAGS) -lang c++ -c" $@ $< -fix-regswaps
-
-"""
-
 # pragma.py 
-# github.com/mparisi20
+# By mparisi20
+# github.com/mparisi20/pragma_processor
 
-# usage: pragma.py cc cflags output source [-fix-regswaps]
+# #pragma regswap usage:
+# #pragma regswap start end regA regB startFile
 
-# TODO: add instruction swap option
-# TODO: add "#pragma startaddr 80000000" to avoid rewriting the start address in each regswap pragma?
+# start: absolute address of start of affected region (hex)
+# end: absolute address of end of affected region (hex)
+# regA: register to swap (r0-r31 or f0-f31)
+# regB: register to swap (r0-r31 or f0-f31)
+# startFile: absolute address of the first function provided by this file (hex)
 
+# TODO: add support for an instruction swap pragma
+# TODO: add "#pragma startaddr <hex-addr>" to avoid rewriting the start address in each regswap pragma?
 
 import os
 import sys
@@ -181,7 +170,6 @@ class PPCInstr:
     
     # returns a tuple containing the bit position of each register field
     # or None if the instruction does not use registers
-    # TODO: exception handling?
     def get_reg_fields(self):
         opcode = self.get_opcode()
         ext_opcode = self.get_ext_opcode()
@@ -198,9 +186,9 @@ class PPCInstr:
     
     # edit the PPC instruction to swap the registers
     def swap_registers(self, regA, regB):
-        DEBUG_v = hex(self.v)
+        # DEBUG_v = hex(self.v)
         reg_fields = self.get_reg_fields()
-        print(str(reg_fields) + ", " + DEBUG_v)
+        # print(str(reg_fields) + ", " + DEBUG_v)
         if reg_fields is None:
             return
         for left in reg_fields: