diff --git a/docs/developers/command-line/basics.md b/docs/developers/command-line/basics.md new file mode 100644 index 0000000..7159748 --- /dev/null +++ b/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. + + + +#### 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! diff --git a/docs/developers/command-line/input.md b/docs/developers/command-line/input.md new file mode 100644 index 0000000..02c1d35 --- /dev/null +++ b/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 +``` diff --git a/docs/networking.md b/docs/developers/command-line/networking.md similarity index 85% rename from docs/networking.md rename to docs/developers/command-line/networking.md index 0dbd4c8..9b4b591 100644 --- a/docs/networking.md +++ b/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 diff --git a/docs/developers/debugging.md b/docs/developers/debugging.md new file mode 100644 index 0000000..4367989 --- /dev/null +++ b/docs/developers/debugging.md @@ -0,0 +1,21 @@ +Depending on the task at hand, it may be necessary to debug XQEMU. + +## Debugging XQEMU code + +#### Windows +The [Visual Studio Code](https://code.visualstudio.com/) IDE can be used to launch and debug XQEMU. A sample launch.vs.json file which can be used to launch XQEMU from code [can be found here](https://raw.githubusercontent.com/xqemu/xqemu.com/master/samples/launch.vs.json). + +#### macOS +##### Using Xcode +Create a project, edit the "Scheme" to run the xqemu binary, then click the run +button. Xcode has a nice GUI for analyzing the stack frame and looking at local +variables to quickly track down bugs. You can also attach to running processes. + +#### Linux +GDB works of course. [Eclipse](https://www.eclipse.org/cdt/) can also be used +for those wanting a graphical source-level debugging solution. + + +## Graphics debugging + +[apitrace](https://apitrace.github.io/) is useful for tracking down rendering bugs. diff --git a/docs/developers/index.md b/docs/developers/index.md index 38c66ba..405ad59 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -31,39 +31,4 @@ Building From Source Code -------------------- For directions on how to build XQEMU from source, please refer to [this page](building.md). -Debugging Guest Code --------------------- -* QEMU can host a gdb stub! Launch with ```-s -S```, and with gdb run `target remote localhost:1234` - * Protip: 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! -* 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 -* [apitrace](https://apitrace.github.io/) is useful for tracking down rendering bugs. - -Debugging XQEMU Itself ----------------------- -Depending on the task at hand, it may be necessary to debug XQEMU itself. - -### Windows -The [Visual Studio Code](https://code.visualstudio.com/) IDE can be used to launch and debug XQEMU. A sample launch.vs.json file which can be used to launch XQEMU from code [can be found here](https://raw.githubusercontent.com/xqemu/xqemu.com/master/samples/launch.vs.json). - -### macOS -#### Using Xcode -Create a project, edit the "Scheme" to run the xqemu binary, then click the run -button. Xcode has a nice GUI for analyzing the stack frame and looking at local -variables to quickly track down bugs. You can also attach to running processes. - -### Linux -GDB works of course. [Eclipse](https://www.eclipse.org/cdt/) can also be used -for those wanting a graphical source-level debugging solution. - -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 diff --git a/docs/getting-started.md b/docs/getting-started.md index ef95175..fa4e382 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -79,10 +79,7 @@ to do this [can be found here](https://github.com/xqemu/xqemu-hdd-image). Running XQEMU ------------- -XQEMU is launchable via the command-line interface, or through the [XQEMU-Manager -GUI](https://github.com/xqemu/xqemu-manager). - -### Using XQEMU-Manager +XQEMU is launchable through the [XQEMU-Manager GUI](https://github.com/xqemu/xqemu-manager). XQEMU-Manager is a simple application with a graphical interface that allows you to easily configure, launch, and control XQEMU. Currently it is distributed separately @@ -102,26 +99,3 @@ following dialog: After configuring your settings, close the settings dialog and click the Start button to launch XQEMU. - -### Using the Command-Line Interface - -You can launch with the following command: - - ./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. diff --git a/docs/input.md b/docs/input.md index 20df8cf..434b373 100644 --- a/docs/input.md +++ b/docs/input.md @@ -1,43 +1,26 @@ -XQEMU currently supports three options for connecting one or more virtual +XQEMU currently supports two options for connecting one or more virtual gamepads: 1. Using an SDL2-supported input device to emulate an Xbox controller 1. Using your PC's keyboard to emulate an Xbox controller -1. Using a real Xbox controller with USB pass-thru (advanced) -And like a real Xbox, you can connect multiple controllers! +And like a real Xbox, you can connect up to 4 input devices! -In all cases, start by making sure you have the `-usb` option specified on the -XQEMU command line. +# Options -## Option 1: Use an SDL2-supported input device +## Gamepad: Use an SDL2-supported input device This method is known to work well with Xbox 360 and DualShock 4 controllers, with little to no setup required (with the exception of installing any required platform drivers). -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 +## Keyboard: Use your PC keyboard If you do not have access to a real gamepad, you can use your PC's keyboard to emulate an Xbox gamepad. This works well in a pinch, and for for navigating through menus. -When starting XQEMU, simply pass in the following option: - - -device usb-xbox-gamepad - -If you'd like, you can combine this device with the `usb-xbox-gamepad-sdl` -device to emulate connecting two controllers. The input can't be configured at -the moment but the following buttons are mapped: +The input can't be configured at the moment but the following buttons are mapped: | Xbox | PC Keyboard | | ----------: | :-------------- | @@ -65,91 +48,3 @@ the moment but the following buttons are mapped: | [Right-Thumbstick](http://xboxdevwiki.net/images/thumb/9/9d/Input-r.png/32px-Input-r.png)-Left | J | | [Right-Thumbstick](http://xboxdevwiki.net/images/thumb/9/9d/Input-r.png/32px-Input-r.png)-Right | L | | [Right-Thumbstick](http://xboxdevwiki.net/images/thumb/9/9d/Input-r.png/32px-Input-r.png)-Press | M | - -## Option 3: 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 have 2 options to forward -the xbox gamepad. - -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: - - SUBSYSTEMS=="usb", ATTRS{idVendor}=="045e", ATTRS{idProduct}=="0288", GROUP="users", MODE="660" # Hub - SUBSYSTEMS=="usb", ATTRS{idVendor}=="045e", ATTRS{idProduct}=="0289", GROUP="users", MODE="660" # Gamepad - -#### 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 -``` - -## Advanced Info - -### About XID and QEMU USB - -The Xbox uses so called [Xbox Input Devices (XID)](http://xboxdevwiki.net/Xbox_Input_Devices). - -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 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). - -### Emulated XID - -There is XID emulation in XQEMU which emulates a very basic Duke Xbox Controller -(VID: 0x045e, PID: 0x0202). - -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 - diff --git a/mkdocs.yml b/mkdocs.yml index 143c17d..4fd349f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -91,10 +91,14 @@ pages: - Welcome: index.md - Screenshots: screenshots.md - Getting Started: getting-started.md - - Input Devices: input.md - - Networking: networking.md - - Tips: tips.md + - Input Devices Settings: input.md - FAQ: faq.md + - Tips: tips.md - Developers: - Welcome: developers/index.md - - Building: developers/building.md + - Building XQEMU: developers/building.md + - Debugging XQEMU: developers/debugging.md + - Command-Line: + - Basics: developers/command-line/basics.md + - Input: developers/command-line/input.md + - Networking: developers/command-line/networking.md