Build instructions cleanup + Windows instructions

BUILD.md

@@ -0,0 +1,81 @@
+# General build instructions
+
+In order to use IDA DOSBox debugger you need to build two things:
+
+1. Client plugin for IDA (this repository)
+2. Custom version of DOSBox which builds in the IDA debugger server ([other repository](https://github.com/wjp/dosbox))
+
+The custom DOSBox build also requires some of the files in this repository, so you will pass the path to this repository in the `--with-ida-plugin` configure flag when compiling DOSBox. (It doesn’t matter which order they are built in.)
+
+# IDADOS plugin
+
+## Windows
+
+### MSVC
+
+1. Install Microsoft Compiler:
+   * [Visual Studio](https://www.visualstudio.com/downloads/download-visual-studio-vs)
+   * [Visual C++ for Python 2.7](http://www.microsoft.com/en-us/download/details.aspx?id=44266)
+1. Set path to IDA SDK in `build_vs.bat`
+1. Open the Visual C++ command line (or open a command line and run `vcvarsall.bat x86`)
+1. Run `build_vs.bat` and follow its instructions
+
+### MinGW-w64 (i686)
+
+1. Install [msys2](http://repo.msys2.org/distrib/i686/msys2-i686-20160205.exe) and follow the setup instructions
+1. Run `pacman -S mingw-w64-i686-toolchain` to install GCC
+1. (optional) Run `pacman -S mingw-w64-i686-SDL` to install SDL if you also plan to compile DOSBox with MinGW
+1. Set the path to IDA SDK in `build_mingw.sh`
+1. Run `build_mingw.sh` and follow its instructions
+
+**64-bit IDA/DOSBox:** Replace “i686” with “x86_64” in the instructions above.
+
+## Linux
+
+```
+export IDA=/path/to/idasdk64/
+export __LINUX__=1
+perl $IDA/bin/idamake.pl
+```
+
+## Mac OS
+
+```
+export IDA=/path/to/idasdk64/
+export __MAC__=1
+perl $IDA/bin/idamake.pl
+```
+
+---
+
+# DOSBox with IDA debugger support
+
+First, make sure to copy/symlink your IDA library (Linux: `libida.so`, Mac: `libida.dylib`, Windows: `ida.wll`) to your `idasdk/bin` directory. **Windows users:** Rename ida.wll to ida.dll when you copy it! Then, follow the instructions for your platform below.
+
+## 32-bit system (Windows with MinGW-w64 i686, Linux)
+
+```
+./autogen.sh
+./configure --enable-debug=ida32 --with-ida-sdk=/full/path/to/idasdk --with-ida-plugin=/full/path/to/idados
+make
+```
+
+**MinGW-w64 users:** You will need to change the `#if __GNUC__` surrounding the `memicmp` declaration in `idasdk/include/pro.h` to `#if 0` to compile successfully.
+
+## 32-bit DOSBox on 64-bit Linux
+
+```
+./autogen.sh
+CC="cc -m32" CXX="c++ -m32" ./configure --enable-debug=ida32 --with-ida-sdk=/full/path/to/idasdk --with-ida-plugin=/full/path/to/idados --host=i686-pc-linux-gnu
+make
+```
+
+## 32-bit DOSBox on 64-bit Mac OS
+
+(The specific darwin release chosen shouldn’t matter.)
+
+```
+./autogen.sh
+CC="cc -m32" CXX="c++ -m32" ./configure --enable-debug=ida32 --with-ida-sdk=/full/path/to/idasdk --with-ida-plugin=/full/path/to/idados --host=i686-apple-darwin12
+make
+```

README.md

@@ -0,0 +1,46 @@
+# IDA DOSBox debugger plugin
+
+## Authors
+
+* Eric Fry <efry@users.sourceforge.net>
+* Willem Jan Palenstijn <wjp@usecode.org>
+
+## Getting started
+
+1. Download the IDA SDK.
+1. Download the plugin source from https://github.com/wjp/idados.
+1. Download the patched DOSBox source from the 'idados' branch of https://github.com/wjp/dosbox.
+1. Build the plugin and DOSBox as described in the [BUILD.md](./BUILD.md) file.
+
+## Usage
+
+1. Load the executable you are debugging into IDA in the usual manner.
+1. Configure DOSBox with `core=normal`.
+1. Run DOSBox and mount disks, etc. in the usual manner.
+1. In DOSBox, run the binary you want to debug, prefixed with `debug`.
+   e.g. `debug sierra.exe`. DOSBox will pause here while waiting for a
+   connection from IDA.
+1. In IDA, start the debugger, selecting the "Remote DOSBox" debugger.
+   You should be able to leave the connection options at their defaults.
+   The binary and arguments are ignored.
+
+## Notes
+
+This plugin has not been tested on many platforms, but it has been reported to
+work with 32-bit IDA 6.4 Starter on 32-bit Windows (using [MSYS2](http://msys2.github.io/)),
+64-bit Linux, and 64-bit Mac OS X.
+
+The debugger plugin will rebase the program to match the memory location
+in DOSBox, but there have been many bugs with this in older versions of IDA.
+If this is causing problems, try manually rebasing before starting the debugger,
+or even recreating the database at the right offset.
+
+There is a known bug with breakpoints on the program entry point. As a
+workaround, you can use the "Suspend on debugging start" option in IDA if you
+wish to break on starting the process. Breakpoints at other locations should
+work fine.
+
+With a 32-bit IDA, you will have to build a 32-bit dosbox, even on 64-bit
+platforms.
+
+And finally, patches to improve the plugin are most welcome!

build_mingw.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+IDA_SDK=../idasdk69
+
+g++ -D__NT__ -D__IDP__ -DNO_OBSOLETE_FUNCS -DNDEBUG -D_SECURE_SCL=0 -fexceptions dosbox_rstub.cpp rpc_debmod_dosbox.cpp "$IDA_SDK/plugins/debugger/"{debmod,rpc_client,rpc_debmod,rpc_engine,rpc_hlp,tcpip,util}.cpp -Os "-I$IDA_SDK/include" "-I$IDA_SDK/plugins/debugger" -I. -static-libgcc -static-libstdc++ "-L$IDA_SDK/bin" -Wl,--dll,--enable-stdcall-fixup,--dynamicbase,--large-address-aware -lida -lws2_32 -shared -mwindows -odosbox_rstub.plw
+if [ $? -eq 0 ]; then
+    echo "Done! Next steps:"
+    echo "1. Copy dosbox_rstub.plw to your IDA plugins directory"
+    echo "2. Copy libwinpthread-1.dll from /mingw32/bin/libwinpthread-1.dll"
+    echo "   to your IDA directory (NOT the plugins directory), or"
+    echo "   add the MinGW bin directory (which contains libwinpthread-1.dll)"
+    echo "   to your PATH."
+fi

build_vs.bat

@@ -0,0 +1,7 @@
+SET IDASDK=..\idasdk69
+
+cl dosbox_rstub.cpp rpc_debmod_dosbox.cpp "%IDASDK%\plugins\debugger\tcpip.cpp" "%IDASDK%\plugins\debugger\rpc_client.cpp" "%IDASDK%\plugins\debugger\rpc_debmod.cpp" "%IDASDK%\plugins\debugger\debmod.cpp" "%IDASDK%\plugins\debugger\rpc_hlp.cpp" "%IDASDK%\plugins\debugger\rpc_engine.cpp" "%IDASDK%\plugins\debugger\util.cpp" /I"%IDASDK%\include" /I"%INCLUDE%" -I"%IDASDK%\plugins\debugger" /D__NT__ /D__VC__ /D__IDP__ /LD /GF /EHs /Gy /FC /Ox /Oi /DNDEBUG /D_SECURE_SCL=0 /MD /ERRORREPORT:QUEUE /Fedosbox_rstub.plw /link /LIBPATH:"%IDASDK%\lib\x86_win_vc_32\;%LIBPATH%" /DLL /LARGEADDRESSAWARE /DYNAMICBASE "%IDASDK%\lib\x86_win_vc_32\ida.lib"
+@IF %ERRORLEVEL% NEQ 0 GOTO END
+@ECHO.
+@ECHO Done! Copy dosbox_rstub.plw to your IDA plugins directory
+:END

dosbox_rstub.cpp

@@ -1,7 +1,7 @@
 #define REMOTE_DEBUGGER
 #define RPC_CLIENT
 
-char wanted_name[] = "Remote Dosbox debugger";
+char wanted_name[] = "Remote DOSBox debugger";
 #define DEBUGGER_NAME  "dosbox"
 #define PROCESSOR_NAME "metapc"
 #define TARGET_PROCESSOR PLFM_386