diff --git a/Child-Process-Debugging.md b/Child-Process-Debugging.md new file mode 100644 index 0000000..cf568f2 --- /dev/null +++ b/Child-Process-Debugging.md @@ -0,0 +1,47 @@ +# Child Process Debugging + +Cxbx is currently engineering to create and run a new instance of itself (`Cxbx.exe`), known as a child process. + +For development, it is strongly recommended you install [Microsoft Child Process Debugging Power Tool](https://marketplace.visualstudio.com/items?itemName=GreggMiskelly.MicrosoftChildProcessDebuggingPowerTool) to support child process debugging from within Visual Studio. + +Once setup, the extension attaches automatically, and supports all the standard IDE features - **although will not detect symbols inside XBE memory regions** - mapping instead to the `virtual_memory_placeholder` placeholder stub (you will still see callstacks though). + +## Setup + +Install the extensions. You will need to close down any open Visual Studio instances first. + +1. Open the Cxbx-Reloaded project file +2. Open the new configuration window from `Debug -> Other Debug Targets -> Child Process Debugging Settings` +3. From here, check `Enable child process debugging` +4. In the table, double-click to add a new row, and enter `Cxbx.exe` as the process name +5. Leave Action as `Attach Debugger` and `Debugger Type` as `` +6. Make sure `Persist settings to` is set to `Hidden solution user options file (SUO file)` and hit Save (top right) + +You just need to do this once. + +## Usage + +Once emulation has started, Visual Studio will list 2 `Cxbx.exe` processes on the toolbar + +You can re-show this toolbar by checking `View -> Toolbars -> Debug Location`) + +The emulated process will have 2 threads named **Cxbx NV2A VBLANK** and **Cxbx NV2A FIFO** + + +## Cxbx Debugger Workflow + +The Cxbx-Reloaded project includes a basic debugger (written in C#) to support extra Xbox-specific emulation features in addition to debugging the child process. + +**Only one user-mode debugger can be attached to a process at one time** + +With the Child Process extension, you will need to: + +1. Open the Cxbx-Reloaded project file +2. Open the new configuration window from `Debug -> Other Debug Targets -> Child Process Debugging Settings` +3. From here, disable Child Process Debugging on `Cxbx.exe` +4. In the table, double-click to add a new row, and enter `CxbxDebugger.exe` as the process name +5. Leave Action as `Attach Debugger` +6. Set `Debugger Type` as `Managed (v4.6, v4.5, v4.0)` +7. Make sure `Persist settings to` is set to `Hidden solution user options file (SUO file)` and hit Save (top right) + +You just need to do this once.