Add more debugging information

docs/developers/building.md

@@ -1,7 +1,6 @@
-Building XQEMU from Source
---------------------------
+## Building XQEMU from Source
 
-### Building on Windows
+### Windows
 
 Start by installing and setting up [MSYS2](https://www.msys2.org/).
 
@@ -12,10 +11,12 @@ Start by installing and setting up [MSYS2](https://www.msys2.org/).
 
 Once MSYS2 has been installed, install all of the necessary packages by running:
 
-    pacman -S git python3 make autoconf automake-wrapper \
-    mingw-w64-x86_64-libtool mingw-w64-x86_64-gcc mingw-w64-x86_64-pkg-config \
-    mingw-w64-x86_64-glib2 mingw-w64-x86_64-libepoxy \
-    mingw-w64-x86_64-SDL2 mingw-w64-x86_64-pixman
+```
+pacman -S git python3 make autoconf automake-wrapper \
+mingw-w64-x86_64-libtool mingw-w64-x86_64-gcc mingw-w64-x86_64-pkg-config \
+mingw-w64-x86_64-glib2 mingw-w64-x86_64-libepoxy \
+mingw-w64-x86_64-SDL2 mingw-w64-x86_64-pixman
+```
 
 !!! important
 
@@ -25,57 +26,79 @@ Once MSYS2 has been installed, install all of the necessary packages by running:
 
 Clone the repo:
 
-    git clone https://github.com/xqemu/xqemu.git
+```
+git clone https://github.com/xqemu/xqemu.git
+```
 
 Then change directory:
 
-    cd xqemu
+```
+cd xqemu
+```
 
 And build using the build script:
 
-    sh ./build.sh
+```
+sh ./build.sh
+```
 
-### Building on GNU/Linux
+### macOS
 
-!!! note
-
-    These instructions were tested with Ubuntu 18.04. Depending on the
-    Linux distribution being used, these instructions may vary.
-
-Install build deps:
+First make sure you've installed the [Homebrew](https://brew.sh/) package
+manager, then update and install necessary packages:
 
-    sudo apt-get update
-    sudo apt-get install git build-essential pkg-config libsdl2-dev \
-    libepoxy-dev zlib1g-dev libpixman-1-dev
+```
+brew update
+brew install libffi gettext glib pixman pkg-config autoconf pixman sdl2 libepoxy coreutils
+```
 
-Then clone the repo:
+Clone the repo:
 
-    git clone https://github.com/xqemu/xqemu.git
+```
+git clone https://github.com/xqemu/xqemu.git
+```
 
 Then change directory:
 
-    cd xqemu
+```
+cd xqemu
+```
 
 And build using the build script:
 
-    ./build.sh --python=/usr/bin/python3
+```
+./build.sh
+```
 
-### Building on macOS
+### Linux
 
-First make sure you've installed the [Homebrew](https://brew.sh/) package
-manager, then update and install necessary packages:
+!!! note
+
+    These instructions were tested with Ubuntu 18.04. Depending on the
+    Linux distribution being used, these instructions may vary.
 
-    brew update
-    brew install libffi gettext glib pixman pkg-config autoconf pixman sdl2 libepoxy coreutils
+Install build deps:
 
-Clone the repo:
+```
+sudo apt-get update
+sudo apt-get install git build-essential pkg-config libsdl2-dev \
+libepoxy-dev zlib1g-dev libpixman-1-dev
+```
+
+Then clone the repo:
 
-    git clone https://github.com/xqemu/xqemu.git
+```
+git clone https://github.com/xqemu/xqemu.git
+```
 
 Then change directory:
 
-    cd xqemu
+```
+cd xqemu
+```
 
 And build using the build script:
 
-    ./build.sh
+```
+./build.sh --python=/usr/bin/python3
+```

docs/developers/command-line/basics.md

@@ -0,0 +1,94 @@
+As XQEMU is based on QEMU, you can follow [the QEMU User Documentation](http://qemu.weilnetz.de/qemu-doc.html).
+However, there are some quirks and new device types introduced by XQEMU which are described here.
+
+
+## Running XQEMU
+
+!!! important
+
+	The recommended way of launching XQEMU is through XQEMU-Manager.
+	See the [user documentation](getting-started.md) for more information.
+
+	Developers or advanced users can also retrieve the command line that XQEMU-Manager uses internally.
+	This is available in the CLI tab in the settings.
+	It also allows you to add additional arguments.
+
+XQEMU emulates a virtual Xbox.
+This implies a Pentium 3 based system with a specific set of ROMs and certain peripherals.
+It is therefore advised to use the following base-command line:
+
+```
+./i386-softmmu/qemu-system-i386 \
+    -cpu pentium3 \
+    -machine xbox,bootrom=$MCPX \
+    -m 64 \
+    -bios $BIOS \
+    -drive index=0,media=disk,file=$HDD,locked \
+    -drive index=1,media=cdrom,file=$DISC \
+    -usb -device usb-xbox-gamepad
+```
+
+Of course, on Windows the executable path will have a `.exe` extension. If launching
+a pre-built binary from AppVeyor, replace `./i386-softmmu/qemu-system-i386` with
+`xqemu.exe`.
+
+Replace the variables `$MCPX`, `$BIOS`, `$HDD`, and `$DISC` with the appropriate
+file paths or define them as variables in your shell.
+
+The Xbox boot animation sequence can be bypassed by adding the
+`,short-animation` option to the `-machine` switch above.
+
+
+### Development Kits
+
+Development kits are similar to retail units. The base command line can be tweaked to emulate them.
+
+Development kits use an MCPX X2 which does not contain the MCPX ROM.
+You can omit the `bootrom` option to skip emulation of the MCPX ROM.
+
+Development kits also use 128MiB of RAM, so you should be using `-m 128` instead of `-m 64`.
+
+Some development kits have had a serial port. This can be emulated in XQEMU.
+XQEMU can emulate a XDK serial port (which with a debug bios hosts KD, as in [this](http://msdn.microsoft.com/en-us/library/hh406279.aspx) and [this](http://www.reactos.org/wiki/Techwiki:Kd))!
+Launch with something like:
+```
+-device lpc47m157 -serial unix:/tmp/xserial,server
+```
+With some effort you can wrestle the unix socket into a vm for with WinDbg.
+<!-- There's also a very barebones perl KD client in scripts/windpl --><!-- FIXME: This script is missing since XQEMU2 -->
+
+
+#### Debug bios
+
+People have reported success with the 'COMPLEX 4627' modified debug bios. It's
+convenient to note that this bios does not necessarily require a _populated_
+hard disk image to load an application from DVD (though an empty drive still
+needs to be attached), so you can skip the next step in some cases.
+
+```
+v1.0.2 1M dump: MD5 (Complex_4627Debug.bin) = 19b5c6d3d42a707bba620634fe6d4baf
+```
+
+_or sometimes_
+
+```
+1MB dump: MD5 (complex_4627debug.bin) = e8dd61cc6abdbd06aac185e371312dc1
+```
+
+### Chihiro
+
+Chihiro support in XQEMU is currently broken. It will be reintroduced in the future.
+
+
+## Useful QEMU options
+
+### Debugging the guest code
+
+QEMU can host a gdb stub!
+
+Launch XQEMU with `-s -S` to start the QEMU gdb stub.
+
+In gdb, connect using `target remote localhost:1234`.
+
+You can also attach to it with [IDA](https://www.hex-rays.com/products/ida/) if you're so inclined.
+You can then load in a database if you export it as a IDC script!

docs/developers/command-line/input.md

@@ -0,0 +1,114 @@
+The Xbox uses so called [Xbox Input Devices (XID)](http://xboxdevwiki.net/Xbox_Input_Devices).
+
+In all cases, start by making sure you have the `-usb` option specified on the
+XQEMU command line.
+To connect multiple gamepads you can simply specify multiple `-device`.
+
+To find out more about QEMU USB emulation you can read [the QEMU User Documentation](http://qemu.weilnetz.de/qemu-doc.html#pcsys_005fusb).
+
+## Connecting a XID
+
+To connect a device to the virtual Xbox you must specify the driver for the
+emulated USB device and the port the device should connect to.
+
+The ports which can be used in XQEMU are:
+
+| Xbox Port | XQEMU USB-Port         |
+| :-------: | :--------------------- |
+| Player 1  | `bus=usb-bus.0,port=3` |
+| Player 2  | `bus=usb-bus.0,port=4` |
+| Player 3  | `bus=usb-bus.0,port=1` |
+| Player 4  | `bus=usb-bus.0,port=2` |
+
+The XID is usually connected to Port 2 of the XID-hub. So if you have a hub for
+Player 1 at `bus=usb-bus.0,port=3`, your gamepad-device would connect to `bus
+=usb-bus.0,port=3.2`.
+
+To recreate the internal XID hub we use the existing QEMU "usb-hub" device.
+The actual XID emulation is provided by the "xbox-gamepad" device.
+
+**Example:**
+```
+-usb -device usb-hub,bus=usb-bus.0,port=3 -device usb-xbox-gamepad,bus=usb-bus.0,port=3.2
+```
+
+## XID emulation
+
+There is XID emulation in XQEMU which emulates a very basic Duke Xbox Controller (VID: 0x045e, PID: 0x0202).
+Alternatively, you can forward a physical XID device from the host into the guest.
+
+
+### Option 1: Use an SDL2-supported input device
+
+When starting XQEMU, simply pass in the following option:
+
+```
+-device usb-xbox-gamepad-sdl,index=0
+```
+
+If you have multiple gamepads connected to your system, you can change the index
+of the connected device by changing `index=X` accordingly.
+
+Multiple gamepads can be connected by specifying the line above multiple times.
+
+
+### Option 2: Use your PC keyboard
+
+When starting XQEMU, simply pass in the following option:
+
+```
+-device usb-xbox-gamepad
+```
+
+The keyboard button mapping is described in the [user section](input.md).
+
+## XID USB-passthru (advanced)
+
+XQEMU has the option to forward USB Devices from the host to the guest.
+The input might be delayed, but it will support all features you'd expect.
+In theory even memory units or the communicator should work!
+
+You can either forward the hub or just the gamepad.
+
+
+To be able to forward any of the host devices you must take the following steps:
+
+1. Have an [adapter cable (this one has not been tested yet!)](http://www.amazon.com/XBOX-USB-Controller-Converter-Gamepad-Adapter/dp/B00CD0KFU0) or [build one yourself*](http://www.ocmodshop.com/how-to-use-an-xbox-controller-as-a-usb-pc-gamepad/3/)
+2. Have libusb installed
+3. Find the VID:PID (Vendor and Product ID) of the XID-Hub and/or the internal Gamepad device
+4. Make sure that libusb has the necessary permissions
+
+!!! important
+
+	Please do not destroy original controllers. Instead buy an adapter cable, or
+	a cheap break-away or extension cable. By cutting it in half you can create
+	2 USB adapters: 1. USB to Xbox + 2. Xbox to USB. You can still use your
+	adapters as an extension cable for most XIDs (not working with lightguns).
+
+On Linux you can use `lsusb` for step 2. Step 3 involves adding a udev rule on
+most linux distributions. The udev rule (/etc/udev/rules.d/999-xbox-gamepad.rules) for a Controller-S could look like this:
+
+```
+## Hub
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="045e", ATTRS{idProduct}=="0288", GROUP="users", MODE="660"
+## Gamepad
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="045e", ATTRS{idProduct}=="0289", GROUP="users", MODE="660"
+```
+
+#### Hub-Forwarding
+
+To forward the entire hub of the controller we simply have to forward the hub to the emulated xbox.
+
+**Example:**
+```
+-usb -device usb-host,bus=usb-bus.0,port=3,vendorid=0x45e,productid=0x288
+```
+
+#### Gamepad-Forwarding
+
+For Gamepad forwarding we create a virtual hub using QEMU and connect the XID gamepad device to port 2 of the emulated hub.
+
+**Example:**
+```
+-usb -device usb-hub,bus=usb-bus.0,port=3 -device usb-host,vendorid=0x45e,productid=0x289,bus=usb-bus.0,port=3.2
+```

docs/networking.md → docs/developers/command-line/networking.md

@@ -1,5 +1,3 @@
-Networking Options
-------------------
 XQEMU emulates the Xbox network controller (nvnet), and being built on top of
 QEMU's robust networking support infrastructure, provides a flexible array of
 advanced network configuration options including:
@@ -11,24 +9,25 @@ advanced network configuration options including:
 - User networking, for simple network use where only basic port-forwarding is
   required.
 
-This page contains some quick tips for common use cases regarding Xbox
-emulation. Additional details about networking configuration information is
-available in the [official QEMU
-documentation](https://wiki.qemu.org/Documentation/Networking).
+This page contains some quick tips for common use cases regarding Xbox emulation.
 
-Bridged Networking
-------------------
+Additional details about networking configuration information is available in the [official QEMU documentation](https://wiki.qemu.org/Documentation/Networking).
+
+## Bridged Networking
 
 ### Windows
 
-__Requirements__
+**Requirements**
+
 - [OpenVPN TAP Driver](https://build.openvpn.net/downloads/releases/latest/) (Download “Tap-Windows”)
 
 Install the prerequisites then you’ll need to manually bridge your main adapter and the newly created TAP adapter. This is easily done by going to `Network & Sharing Center` then `Change adapter settings`.
 
 The command line options are very similar to Linux however you’ll need to change the `ifname=tap0` to what ever Windows or yourself had set the name of the new TAP adapter to be.
 
-` -net nic,model=nvnet -net tap,ifname="Ethernet 2",script=no`
+```
+-net nic,model=nvnet -net tap,ifname="Ethernet 2",script=no
+```
 
 In this example the interface name is `Ethernet 2`.
 
@@ -37,7 +36,8 @@ In this example the interface name is `Ethernet 2`.
 
 ### Linux
 
-__Requirements__
+**Requirements**
+
 - uml-utilities
 - bridge-utils