start of contribution guide

CONTRIBUTE.md

@@ -0,0 +1,140 @@
+# Contribution Guide
+
+This guide outlines useful resources, tools and processes for contribution to
+Devilution.
+
+## Useful Repos
+
+* [diasurgical/scalpel](https://github.com/diasurgical/scalpel) - uploaded .SYM
+  files from each realese of Diablo 1 on Playstation
+* [sanctuary/notes](https://github.com/sanctuary/notes) - documented
+  Windows-specific Diablo code
+
+## Software and Utils
+
+* A clean installation of Diablo patched to version 1.09b (Diablo.exe)
+* Download IDA (Interactive Disassembler) [Hex-Rays](https://www.hex-rays.com/products/ida/support/download_freeware.shtml)
+* Download IDC script from sanctuary/notes repository: [notes.idc](http://sanctuary.github.io/notes/notes.idc)
+
+## How To...
+
+Described below are steps for using the IDA and SYM files to reverse the Diablo
+source.
+
+### Understanding Devilution and Sancutary Notes
+
+Both Devilution and the Sanctuary Notes repo have the intended aim to get as
+close as possible to document the original game. Devilution is closer in the
+sense that the same names have been used for functions as based on the SYM
+debug info. The notes repo has tried to use consistent naming for functions,
+e.g. prefix with source file name.
+
+See for instance [drlg_l1_load_dun](http://sanctuary.github.io/notes/#function/drlg_l1_load_dun),
+which is defined in `drlg_l1.cpp`. This function has the PSX signature
+`void LoadL1Dungeon__FPcii(char *sFileName, int vx, int vy)`, but is documented
+in the Sanctuary Notes repo as follows for consistency:
+
+```cpp
+/// address: 0x40AE79
+///
+/// drlg_l1_load_dun loads tile IDs, monsters and objects from the given
+/// dungeon file.
+///
+/// PSX ref: 0x8013CF64
+/// PSX def: void LoadL1Dungeon__FPcii(char *sFileName, int vx, int vy)
+void __fastcall drlg_l1_load_dun(char *dun_path, int view_x, int view_y);
+```
+
+### Interactive Disassembler Usage
+
+* Open the `Diablo.exe` (verison 1.09b in IDA) and wait for it to finish
+  analysis
+  * Open as "Portable Executable"
+  * Processor type i386 (80386)
+* Run the IDC script in IDA on the fresh IDB database to import names for
+  variables and functions, type definitions, etc. (Note: run the IDC script
+  **only** on new IDB databases as it removes all variable names before adding new
+  ones.); for more info, see [#79 (comment)](https://github.com/diasurgical/devilution/pull/79#issuecomment-400536087)
+* Example: search for `drlg_l1_load_dun`
+  * Starting memory address `0x40AE79`
+  * Funcation name `drlg_l1_load_dun`
+  * Function arguments `(char *dun_path, int view_x, int view_y)`
+  * #TODO whatelse can be inferred from below?
+
+```asm
+; drlg_l1_load_dun loads tile IDs, monsters and objects from the given
+; dungeon file.
+; Attributes: bp-based frame
+
+; void __fastcall drlg_l1_load_dun(char *dun_path, int view_x, int view_y)
+drlg_l1_load_dun proc near
+
+var_C= dword ptr -0Ch
+var_8= dword ptr -8
+var_4= dword ptr -4
+view_y= dword ptr  8
+
+push    ebp
+mov     ebp, esp
+sub     esp, 0Ch
+push    ebx
+push    esi
+push    edi
+push    10h
+pop     eax
+mov     [ebp+var_C], edx
+push    60h
+mov     dword_5D2458, eax
+mov     dword_5D245C, eax
+pop     eax
+mov     esi, ecx
+mov     dword_5CF328, eax
+mov     dword_5CF32C, eax
+call    gendung_init_transparency
+xor     edx, edx        ; size
+mov     ecx, esi        ; file_path
+call    engine_mem_load_file
+mov     esi, eax
+xor     ecx, ecx
+```
+
+### About the SYM
+
+The diasurgical/scalpel repository includes a copy of a symbolic file that was
+accidentally left on the Japanese release of Diablo on Playstation 1. The CD
+contained debug information in a .SYM file, the format of which has been
+reversed, so we can recover type information, variable names, etc, for the PSX
+release.
+
+* Download and open [jap_05291998.out](https://raw.githubusercontent.com/diasurgical/scalpel/master/psx/symbols/jap_05291998.out)
+* Example: search for `LoadL1Dungeon__FPcii`
+  * Starting memory address `0x8013CF64`
+  * Function name `LoadL1Dungeon`
+  * Function arguments `(*char sFilename, int vx, int, vy)`
+  * #TODO whatelse can be inferred from below?
+
+```
+135ea8: $8013cf64 8c Function_start
+    fp = 29
+    fsize = 48
+    retreg = 31
+    mask = $80070000
+    maskoffs = -4
+    line = 905
+    file = C:\diabpsx\SOURCE\DRLG_L1.CPP
+    name = LoadL1Dungeon__FPcii
+135ef4: $00000010 94 Def class REGPARM type PTR CHAR size 0 name sFileName
+135f0b: $00000011 94 Def class REGPARM type INT size 0 name vx
+135f1b: $00000012 94 Def class REGPARM type INT size 0 name vy
+135f2b: $8013cf64 90 Block_start  line = 1
+135f34: $00000005 94 Def class REG type INT size 0 name i
+135f43: $00000007 94 Def class REG type INT size 0 name j
+135f52: $0000000b 94 Def class REG type INT size 0 name rw
+135f62: $0000000c 94 Def class REG type INT size 0 name rh
+135f72: $00000010 94 Def class REG type PTR UCHAR size 0 name pLevelMap
+135f89: $00000008 94 Def class REG type PTR UCHAR size 0 name lm
+135f99: $8013d0c4 90 Block_start  line = 44
+135fa2: $8013d11c 92 Block_end  line = 60
+135fab: $8013d11c 92 Block_end  line = 60
+135fb4: $8013d138 8e Function_end
+```