Xbox:Debug

Do not run the Xbox Devkit Recovery EXE from the XDK on a retail Xbox. You will brick the Xbox. You only need to load (not necessarily flash) a debug bios and copy some files to C: and E: to run an Xbox in Debug mode!

Overview

What is an Xbox debug kit?

A debug kit was an Xbox that was officially released only to software developers, for use in developing Xbox games. Official debug kits had a different BIOS, usually 128MB of RAM, and debug kit files loaded onto the hard drive. They could also be used as a retail Xbox, by switching between retail and debug mode. Software developers used debug kits to run their Xbox games. They could connect to the running game with Visual Studio and monitor crashes and the state of the program while building it. Otherwise, it would run programs in the same way as a normal or modded Xbox. The debug kit, though, had its own dash, with more options than the MS dash, allowing them to launch software from the Xbox hard drive.

• Xbox debug kits are transparent green, like the Halo special edition Xboxes. They say "DEBUG KIT" on the right side of the front of the case, which makes them easy to identify. There were also clear "Development Kit" Xboxes released, which are rare. They have a taller case, and are clear like the crystal Xbox, but they have a green jewel.

Why should you set up your Xbox to run as a debug kit?

Using a modded Xbox, you can enable debug features and use your Xbox as a development station. This means that you can run and debug code in the same way Xbox developers did. To clear up some common misconceptions:

• You don't necessarily need to flash a BIOS, you can load a debug BIOS temporarily with Phoenix BIOS Loader (PBL).
• The debug dash files can coexist with your files on a hardmodded or softmodded Xbox; it's not a permanent or destructive conversion.
• Although official debug kits generally had 128MB of RAM, the extra RAM was only really used to run debug tools on top of the game -- developers were expected to run the game in 64MB of RAM by release. In short, you don't need 128MB of RAM to use your Xbox as a debug kit, it will just increase your ceiling of available memory for software development.

Choosing a Method

There are a few options to setup debugging:

• Option #1: Booting a debug BIOS through an app and using 100% software based debugging over your network. This is the easiest, safest, and most convenient method.
• Option #2: Installing a debug BIOS and dashboard and using 100% software based debugging over your network. This requires you to flash your BIOS.
• Option #3: Installing Xbox7887's hardware debugger board for hardware based debugging over USB. This advanced method allows you to debug the kernel directly from the LPC, but does not work with modchips.

The method you choose depends on what you are trying to accomplish and whether you want to make it a permanent debug kit. On top of any of the options, you can also perform the 128MB RAM upgrade so that the debugging processes don't take as much of system resources, but this can be done at any time.

Setting up the PC

1. Set up a virtual machine running Windows 2000 or Windows XP. You will need to run Windows 2000 or Windows XP in order to run Visual Studio 2003 plus the XDK, on the computer that will be talking to your Xbox. Windows XP is recommended, as it received support updates for a longer period than Windows 2000. Either 32-bit or 64-bit Windows XP will work, but it's unlikely you will need more than 4GB of RAM and most applications are not 64-bit only. It's worth noting that 64-bit Windows seems to have problems with the explorer shell integration from the XDK, so it's recommended to go with 32-bit.
   • Alternatively, you can use a dedicated PC or laptop instead of a virtual machine, but since you will be able share directories on a virtual machine with the parent system and you can use up-to-date tools on the parent system for source control or 64-bit tools.
2. Download Visual Studio .NET 2003 or Visual C++. Typically to compile code for your Xbox, you will use Microsoft Visual Studio with C++ installed. Visual Studio .NET 2003 is usually used, as it is the latest version that supports the XDK (Xbox Development Kit). Microsoft Visual C++ .NET 2003 is also fine and will have what you need for Xbox development. The easiest way to install these is to mount the ISOs.
3. Start up Visual Studio setup and Install Prerequisites. If you are told to install the prerequisites, get the "MSDN Visual Studio NET 2003 Prerequisites" and install those. DO NOT install Visual Studio 2003 Service Pack 1/Security Releases
4. Configure Visual Studio 2003 Setup. You should be able to skip most of the enterprise related and non-C++ stuff, if you find you you need anything later you can add it later by going to Add/Remove Programs, choosing Visual Studio or Visual C++, and choosing Change/Remove, and the files will be copied from the CD. If space is not at a premium, you can just install the whole thing if you want.
5. Install Visual Studio 2003, or Visual C++ 2003. After those are installed, you can also install the MSDN CDs with general Visual Studio documentation if you want, but this is unnecessary; you only need the prerequisites and Visual Studio/C++.
6. Install DirectX Update. Install the DirectX 9.0 SDK Update (Summer 2004). It's required to build later apps such as XBMC.
7. Install XDK 5849. Now that you have Visual Studio installed, you need to install the XDK. The latest official XDK build is 5849. There is a build, 5933, with a higher revision number, thought to be used for internal development, but it was made at an earlier date and any improvements are assumed to have been added in 5849.
   • You may see a file XDKRecovery[XDK version]External.exe. NEVER RUN THIS FILE unless you have an official Debug Kit Xbox from Microsoft. It will brick retail Xboxes. You want to run the file XDKSetup5849.exe instead.
   • If you have installed Visual Studio 2003 Service Pack 1 already, you must run the setup file with the command line argument "/s", or else setup won't work. If you didn't install VS2003 Service Pack 1, you shouldn't need to do this.
8. Install the Windows Explorer Shell Extension for Xbox. Run XBSESetup.exe to integrate your Xbox with Windows Explorer. You can access various drives on your Xbox, but you don't get full access to all the drives.
   • If you are on Windows XP 64 bit, you will notice that the Xbox Neighborhood icon does not show up. To fix it, create a new shortcut on your Desktop. For the Target Location, enter %windir%\syswow64\explorer.exe ::{DB15FEDD-96B8-4DA9-97E0-7E5CCA05CC44}, /separate. Name the shortcut "Xbox Neighborhood". Right click it, click Properties > Change Icon, and point it to %windir%\syswow64\xbshlext.dll, choosing the icon that has the word "Xbox" on it and click OK.
9. Install Visual Studio 2003 Service Pack 1 (optional, not recommended, can't run the XDK samples. Note that if you do this, you will need to use the "/s" argument for future XDK installations, e.g. "XDKSetup5849.exe /s". Also, the XDK samples seem to fail to convert to the new project format when opened, if you've installed Service Pack 1.
   • If you are running Windows 2000, you will need to install Windows Media Player 9. Optional, but some of the DLLs are required to build some of the SDK samples. Some stripped down versions of XP also install without Windows Media Player.

Setting up the Xbox

1. Backup your C: and E: drives by copying the contents to your PC. If shadowc.img exists and your Xbox is TSOP flashed with a custom BIOS and has an unlocked HDD, you can delete shadowc.img AFTER you backup your drive.
   • Don't delete shadowc.img if your Xbox is only softmodded! As always, you shouldn't delete anything from C: if your Xbox is softmodded unless you know what you're doing and have a known and tested path to recovery such as hotswapping or a modchip.
2. Copy the debug files to your C: and E: drives. Follow the directions below depending on whether you downloaded a pack that included C: and E: files already separated out or whether you only have XDK Recovery EXE.

If you only have a XDK Recovery EXE

If you only have an XDK Recovery EXE instead of sorted C: and E: files, you will need to use WinRAR to unzip the files directly from the recovery EXE. DO NOT EVER RUN THE RECOVERY EXE, IT WILL BRICK YOUR XBOX. You only need the files listed below, don't copy anything else. If a file already exists, do not overwrite it.

• Put all the files in DEVKIT\ in E:\DEVKIT
• Rename E:\DEVKIT\dxt\vx.dxt to vx.dxt.old. This is needed to run the MS debug dashboard from a BFM bios (info here. If you are going to flash a debug BIOS to TSOP, you shouldn't have to rename this file. If you don't delete it, your Xbox will be FRAYing (flashing red and yellow) when you run the BFM bios.
• Ignore TDATA, this just adds some soundtrack music and will overwrite your custom soundtrack, possibly.
• Put XDASH\xshell.xbe in C:\xshell.xbe
• Put all the files in XDASH\Audio\ in C:\Audio
• You already have the fonts; skip XDASH\Fonts
• Put all the files in XDASH\Images\ in C:\Images
• Put all the files in XDASH\Media\ in C:\Media
• Put all the files in XDASH\Sounds\ in C:\Sounds
• You can put XDKSAMPLES in E:\DEVKIT\XDKSAMPLES if you want to view the samples; this is optional. Many samples including these come with the XDK, and you can build and run them whenever you want.
• Put XBOX\dashboard.xbx in E:\dashboard.xbx
• Put XBOX\xbdm.dll in E:\xbdm.dll
• Skip XDASHDATA and anything else not mentioned.

If C: and E: are Provided

Copy over the devkit C: and E: files to your Xbox, manually. NEVER RUN THE XDK RECOVERY TOOL. There are a number of packs floating around with debug Xbox files, many of which include files that you don't need. You only need to install the files in this list. Some of these files may already exist on the drive; it's recommended to skip copying those as they should be the same file.

• Files for the C: drive:
  • C:\xshell.xbe
  • C:\data\saveimage.xbx
  • C:\data\titleimage.xbx
  • C:\media\arialuni.ttf
  • C:\media\locale.strings
  • C:\media\tahoma.ttf
  • C:\media\XBOX_BD.TTF
  • C:\media\XBOX_RG.TTF
  • C:\media\xbox.ttf
  • C:\media\xboxdings.ttf
  • C:\media\xlaunch.strings
  • C:\images\logow.bmp
  • C:\images\arrow_down.bmp
  • C:\images\arrow_sublist1.dds
  • C:\images\arrow_sublist2.dds
  • C:\images\arrow_up.bmp
  • C:\images\background1.bmp
  • C:\images\background2.bmp
  • C:\images\button_a.bmp
  • C:\images\button_b.bmp
  • C:\images\button_black.bmp
  • C:\images\button_white.bmp
  • C:\images\button_x.bmp
  • C:\images\button_y.bmp
  • C:\images\image_mask.dds
  • C:\images\image_missing.bmp
  • C:\images\image_xbox.dds
  • C:\images\logo.bmp
  • C:\sounds\back_button.wav
  • C:\sounds\error.wav
  • C:\sounds\keyboard_stroke.wav
  • C:\sounds\menu_item_select.wav
  • C:\sounds\select_button.wav

• Files for the E: drive:
  • E:\dashboard.xbx
  • E:\xbdm.dll
  • E:\xbdm.dll_old
  • E:\DEVKIT\xonline.ini
  • E:\DEVKIT\cert\friend\CertFriend.xbc
  • E:\DEVKIT\cert\friend\media\font.xpr
  • E:\DEVKIT\cert\friend\media\gamepad.xpr
  • E:\DEVKIT\cert\friend\media\resource.xpr
  • E:\DEVKIT\cert\invite\CertInvite.xbc
  • E:\DEVKIT\cert\invite\media\font.xpr
  • E:\DEVKIT\cert\invite\media\gamepad.xpr
  • E:\DEVKIT\cert\invite\media\OnlineIconsFont.xpr
  • E:\DEVKIT\dxt (EMPTY DIRECTORY; CREATE IF DOESN'T EXIST)
  • E:\DEVKIT\Tools (EMPTY DIRECTORY, MAY INCLUDE UNLEASHX. CREATE IF DOESN'T EXIST)

• Any files not in the above lists, you should be able to safely delete, as these are likely just unrelated files from someone else's Xbox.

Setting up the Xbox (continued)

Put a recovery dash in E:\DEVKIT\Tools. You should put a copy of UnleashX or another custom dashboard in the Tools directory so that the default.xbe is in a subfolder inside Tools (e.g. E:\Tools\UnleashX\default.xbe). This allows you to load another dashboard from the MS debug dashboard, enabling you to do file browsing, initiate a LAN connection for recovery, or to launch BIOS flashing if your Xbox gets stuck booting from the MS dash. You could also put a full copy of your normal dashboard in here.

(Option #1) Setting up PBL

1. Choose a BIOS and rename it. There are a number of debug BIOSes you can use with your Xbox, including the Microsoft debug BIOS, which is 1MB. The Yoshihiro Debug Bios is also a well-regarded 256k debug BIOS. You will need one labeled Bootable From Media (BFM), as that is the only bios type that is can be loaded from your hard drive using Phoenix BIOS Loader. Rename the BIOS' .bin file to xboxrom.bin.
   • IND-BIOS 5004.67 BFM supports debugging if enabled in the ind-bios.cfg file on your hard drive by setting DISABLEDM=0 to enable the debug monitor.
2. Configure Phoenix BIOS Loader. Copy the BIOS xboxrom.bin file, the Pheonix BIOS Loader XBE, and the boot.cfg file into the E: drive of your Xbox.
3. Launch the PBL default.xbe on your Xbox. If all went well, the LED of your Xbox should turn orange and your Xbox should boot to the MS debug dash. If not, you may have a black screen, or no video, and FRAG or FRAY. You may need to pull the power on your Xbox to get it to boot normally again -- turning it off and on with the power switch seems to cause the state to persist sometimes. You will need to figure out why this isn't working on your Xbox. If you have problems, make sure you renamed E:\DEVKIT\dxt\vx.dxt to something else, if it exists. You may need to try a different BFM BIOS.

(Option #2) Flashing a Debug BIOS

Flashing a debug BIOS is the same as flashing a regular BIOS. Do not flash the Microsoft debug bios or any other >256k BIOS to your TSOP or modchip unless you know that the flash chip can accept that size. Also worth noting, IND-BIOS 5004.67 supports debugging if enabled in the ind-bios.cfg file in your C: drive by setting DISABLEDM=0 to enable the debug monitor. If all went well, when you power on the Xbox, the eject button LED should turn orange and your Xbox should boot to the MS debug dash.

Finishing Setup

1. Name your Xbox. Upon launching the debug dashboard for the first time, you may be prompted to provide a name for your Xbox. Your Xbox may have a name already set by a handful of games. This is how the Xbox will (theoretically) show up in Windows. For some reason it seems unreliable to get Windows to call your Xbox by its name rather than its IP.
2. Familiarize yourself with the MS Debug Dash. Look around the settings, but don't touch anything unless you're sure of what it does. If you had put a dashboard in E:\DEVKIT\Tools, you should be able see and launch this dash in the XDK Launcher menu. Immediately, you can begin debug executables remotely.
3. Connect your Windows 2000/XP network to your home network. If you are using a VM, you will need to setup your network connection to be bridged with your host PC's connection.
4. Add your Xbox to Xbox Neighborhood. If you installed the Xbox Windows Explorer shell extension previously, launch the MS Dashboard on your Xbox. On your PC, you should see an icon on your desktop called "Xbox Neighborhood". Click this icon, and choose "Add Xbox". Try your Xbox nickname from the debug dash, but you might have to add your Xbox by IP. Through Xbox Neighborhood in Windows Explorer, you can now access different areas of your Xbox's hard drive. There are mod files that will allow you to modify the XDK to access more of the Xbox HDD (not covered here).
   • Alternately, in command prompt type xbdir -x [YOUR XBOX NAME OR IP] xe:\ to add your Xbox to Xbox Neighborhood.
5. Start an Xbox project in Visual Studio. Open Visual Studio, and go to the Projects tab. You can set the Profile to Visual C++ developer if you want. Open the "Projects" tab. Click on "Visual C++ Projects", and in the right hand pane choose "Xbox Project". Give your project a name, use the default settings and press "Finish".
6. Start a debugging session for the default project. You do not need to be running the MS dash to do it; you just need a debug BIOS running. In Visual Studio, press Play in the upper toolbar your project will build, and the current app will quit, your app will begin running, and you should see a spinning triangle on your screen. If not, you may be prompted to set your Xbox's IP first. If you have connection problems, make sure your VM network connection is set to bridged. If you press the Stop button at the top, you'll go back to the MS debug dash.
7. Read the docs! Take a look at the help file located in C:\Program Files\Microsoft Xbox SDK\docXboxSDK.chm. These documents are quite accessible as far as software documentation goes, and reading through a good portion of them is strongly recommended. There's a lot of useful information in here to understand how Xbox game development was intended to be done, including information that will be relevant to any homebrew app.
8. Develop amazing software for the Xbox. Now you are able to start developing, improving, and sharing Xbox applications! There are a ton of sample projects provided in C:\Program Files\Microsoft Xbox SDK\Samples that you can build and run on your Xbox. You can also download open source existing Xbox projects and run them.

Tips

• If you want to downgrade the XDK, the XDK won't allow you to install an earlier version, even if you uninstall the previous one. The workaround for this is to remove the registry keys HKEY_LOCAL_MACHINE\Software\Microsoft\XboxSDK and HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\Microsoft Xbox SDK before installing an earlier version.

• The XDK xe:\ drive is the E:\DEVKIT folder. On the MS debug dash, it searches one subdirectory deep for directories containing XBEs, so you can group your projects by folder but they will only show up in the MS Dash if the XBE is 2 folders deep or less in E:\DEVKIT, e.g. E:\DEVKIT\MyApps\MyTestApp\default.xbe would be the greatest depth you could put an XBE.

• You can attach to a debug executable after it's already running, even after it's entered an exception state. So, if your app unexpectedly crashes even while you're not in a debugging session, you can attach to it (assuming you have a debug BIOS and that compiled code in Visual Studio on your Windows instance, which is pretty likely).

• A flashing red and yellow/orange normally means that your console has RAM issues. If this happens with a debugger attached, though, it means your console is dumping core. A core dump will appear in the DEVKIT folder, and it will be the size of your RAM.

• It's possible to debug on multiple Xboxes simultaneously, by starting two instances of Visual C++, and changing the default Xbox between debugging sessions. xbdir -x [NAME OR IP OF XBOX] will change the default Xbox.