Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move command-line documentation to Developer area #60

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Move command-line documentation to Developer area #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions docs/developers/command-line/basics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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!
114 changes: 114 additions & 0 deletions docs/developers/command-line/input.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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` |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might need a future PR, but this table was reported on discord as incorrect recently.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's incorrect?
However, please create a separate issue about this. This moves content, but doesn't really modify it.


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
```
22 changes: 11 additions & 11 deletions docs/networking.md → docs/developers/command-line/networking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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`.

Expand All @@ -37,7 +36,8 @@ In this example the interface name is `Ethernet 2`.

### Linux

__Requirements__
**Requirements**

- uml-utilities
- bridge-utils

Expand Down
21 changes: 21 additions & 0 deletions docs/developers/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
35 changes: 0 additions & 35 deletions docs/developers/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
28 changes: 1 addition & 27 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -102,26 +99,3 @@ following dialog:

After configuring your settings, close the settings dialog and click the
<kbd>Start</kbd> 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.
Loading