From 4736414beddefdf68a765f99bf9bd3779714b471 Mon Sep 17 00:00:00 2001 From: James Lambert Date: Thu, 23 Mar 2023 22:44:35 -0600 Subject: [PATCH] Document how to use the debugger with the evedrive --- documentation/debugger.md | 158 ++++++++++++++++++++++++++++++++++++++ tools/romfix64.exe | Bin 0 -> 6144 bytes 2 files changed, 158 insertions(+) create mode 100644 documentation/debugger.md create mode 100755 tools/romfix64.exe diff --git a/documentation/debugger.md b/documentation/debugger.md new file mode 100644 index 0000000..2b8899c --- /dev/null +++ b/documentation/debugger.md @@ -0,0 +1,158 @@ +# Debugger + +To get the debugger working with portal64 you should clone these two repos somewhere on your harddrive + +[https://github.com/lambertjamesd/libultragdb](https://github.com/lambertjamesd/libultragdb) + +[https://github.com/lambertjamesd/gfxvalidator](https://github.com/lambertjamesd/gfxvalidator) + +You then need to create the following symbolic links in the root portal64 directory + +```bash +~/portal64$ ln -s /path/to/libultragdb/debugger debugger +~/portal64$ ln -s /path/to/gfxvalidator/debugger gfxvalidator +``` + +If done correctly, the folder structure should look like + +``` +portal64/ + debugger/ + debugger_stub.c + debugger.c + debugger.h + rsp.c + rsp.h + serial.c + serial.h + gfxvalidator/ + command_printer.c + command_printer.h + error_printer.c + error_printer.h + gfx_macros.h + validator.c + validator.h +``` + +Next, you need to configure an environment variable. Put this in your `~/.bashrc` or `~/.profile` + +``` +export PORTAL64_WITH_DEBUGGER=1 +``` + +Then to build the rom with the debugger in it, use ths make command + +``` +PORTAL64_WITH_GFX_VALIDATOR=1 make build/portal_debug.z64 +``` + +This will build a version of the game that has a debugger installed. When the game boots, it will pause and wait for something to connect to the debugger before continuing. To connect the debugger with an everdrive, you will need to run the following script. + +``` +node /path/to/libultragdb/proxy/proxy.js /dev/ttyUSB0 8080 +``` + +This listens on port 8080 for gdb to connect and when it does, it relays connection to the everdrive found at /dev/ttyUSB0. If you get any permssions errors accessing ttyUSB0, change them before trying to debug + +``` +chmod 666 /dev/ttyUSB0 +``` + +Once the proxy is running you can then connect gdb to port 8080. You will want to use `gdb-multiarch` since this is debugging a MIPS cpu. You can install this version of gdb using apt + +``` +sudo apt install gdb-multiarch +``` + +I use vscode to debug with [GDB Debugger - Beyond](https://marketplace.visualstudio.com/items?itemName=coolchyni.beyond-debug) with this launch configuration + +`.vscode/launch.json` +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "by-gdb", + "request": "launch", + "name": "Debug with EV", + "program": "${workspaceFolder}/build/portal_debug.elf", + "cwd": "${workspaceRoot}", + "debuggerPath": "gdb-multiarch", + "remote": { + "enabled": true, + "address": ":8080", + "mode": "remote", + "execfile": "${workspaceFolder}/build/portal_debug.elf" + }, + "commandsBeforeExec": [ + "set arch mips:4300", + ], + "preLaunchTask": "Run EV delay", + } + ] +} +``` + +This expects the task configuration to look like this with the `preLaunchTask` `Run EV Delay` + +`.vscode/tasks.json` +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Make Debug Rom", + "type": "shell", + "command": "PORTAL64_WITH_GFX_VALIDATOR=1 make build/portal_debug.z64", + "group": "build" + }, + { + "label": "Fix Debug Rom", + "type": "shell", + "command": "${workspaceFolder}/tools/romfix64.exe ${workspaceFolder}/build/portal_debug.z64", + "group": "build", + "dependsOn": "Make Debug Rom" + }, + { + "label": "Upload Debug to EV", + "type": "shell", + "command": "/home/james/everdrive/usb64/usb64/bin/Debug/usb64.exe -rom=${workspaceFolder}/build/portal_debug.z64 -start", + "group": "build", + "dependsOn": "Fix Debug Rom" + }, + { + "label": "Run EV delay", + "type": "shell", + "command": "sleep 3", + "group": "build", + "dependsOn": [ + "Upload Debug to EV" + ] + }, + { + "label": "Start EV Proxy", + "type": "shell", + "command": "node /path/to/libultragdb/proxy/proxy.js /dev/ttyUSB0 8080", + "problemMatcher": [ + "$tsc-watch" + ], + "isBackground": true + } + ] +} +``` + +Where the executable usb64.exe comes from here [https://krikzz.com/pub/support/everdrive-64/x-series/dev/](https://krikzz.com/pub/support/everdrive-64/x-series/dev/). It is a windows executable but is compatible with [wine](https://www.winehq.org/). I am running wine-8.0 which you need to install manually instead of using apt. + +romfix64.exe is also a windows executable compatible with wine. + + +I also have a task `Start EV Proxy` that starts the proxy script for connecting gdb to the evedrive. So my processing for debuging on hardware goes as follows. + +1. run the `Start EV Proxy` task (ctrl + shift + p, then type 'Run Task', the Select the Start EV Proxy task) +1. turn on the console with the everdrive installed and the usb cable connected +1. select Debug with EV in the run and debug tab in vscode +1. Press F5 + +If everything is working correctly the rom will automatically be uploaded to the everdrive and the debugger will connect shortly after that. The debugger will always pause after the debugger is connected and you will need to press continue for the game to run. After you turn off the console you will need to stop the proxy and restart it before debugging again. I have tried to make the proxy automatically start and stop without much success so it is still manual. \ No newline at end of file diff --git a/tools/romfix64.exe b/tools/romfix64.exe new file mode 100755 index 0000000000000000000000000000000000000000..92485335400e3aed8b17308c879b259087406d21 GIT binary patch literal 6144 zcmeHLYiu0V6+Sb&J3G66#N$ouB-rs}gQwTYeGP2yrF!FCb@LCNgytUbx> z%rY};yg;czDutGYM1Yi1+DaAukrwr#RwAOUDpi##(IQo}KWK|u)F1tUNhnY`{BOOlkiH5% z55I>QK1uXKsKTu8P7yVNHhYOW>iHjrtF_R%rVRREolU~iS3S`GX3inwbFIV;iZ_+$ zRKjtcEGQn^BoH=HOsT$2BKm}*n>G}gJ357j`D(*c*CvVf)sY;14fAJ>#U@gSeitXY zfSd_-EsM3eyiDkLv5QFTdX%3w6h&?pU}x zCU?gou_%%NwT7{C&{i6@E?P+2>A_&2u{SO%4d=TyXT)};Vex!dOXifgnPJ<2Y+=Z$ zMkOjQHbs=^h@>FSm<)ePSk_`;xvT4BEQk#DU}Q<|QkCGHJvbbsQ%y=FvKWiViZp^J zqQ#`%h$6v}22=^jN<>?Xg;*r92Bm?&qEznk<;zM`ku@c(MHQ%PN=R#PW|1}NiFTwj z%wZ4EsMysab#2bQ`kdIMNL?))X_dC|J|;2t#&AWxDO{1ag?)K@_|@ljZWDVp!_Q9I zH~*P^0$YJ-Y(K1wBnA@01H*&2GERt0z~5le?0AT19MeqU*)i`qhPC7}jWz5swl{Yi zou_{QXG>tmfuqwY^uaLE({R0GpJ``6vj$hf@lKH;cq$o28Wk8e3$F| zlD-3-Z*h1N=Qjx*;B*J>0$ddtJc~Uq(J05G9Nx;MPZ5*00wO$|#H{(*Y@s=E3r%tA zjx~Xvp*z-e4#zm0@^Pj@9TuO*>Rzi*&wvWig$mUd z_%?;Z(tB}lmg@QI6Xp1@V5mH z&=2UVGz)wNOL69BU2Nn*} zeA)H%LSp*xy5wMbDwUo)a(I57HNP-5w?H|~)2QHPZO1e+w4{3{XLZ-rmUP;0m^vkG z%eB!TcMMOTF)W=9l#JYzhYg!4c{-)^OlfIJ%b5B)FKHK!8Ln{!Z_0J`LdGmF7+$?< zjqPYTy`VW~*1arf4x-tQVn)But`}5oSbWEH$2Dwg-Kr`?+<9ZEu9?CbyW=O>LE9?zO&;ICu$J?^;39E|wi*Y5BUMLQ%8I>o#*G%QFf(8x!MX4Ab!H zr2ERqZS}1u^i{q3PAg`K%EWPMl7Dzo+RC}d4R4w9hH0K$(M)npLa3}9tXR{mW>_^( zdfwEtECZBY&FVZCWVrim+ncfRHXKT1J=-DIsam8AZOO7-&&aw}Ry7Q2HY$*mrs0rZPBMxRCh08X+hMKtmFTMryv7@K_Jdz;?AZ6Y0`ze3qcy>xx;$~G3XIn- zP-|@ms6W4`szU>VV@S6^H|nFg>}Y=Umj2=0yNCKmhKF|dXSBggzpf1o?;go#vYEjl z)C&TI2T?BIM>H!?N8(U=p>_iFRo46jN{Z3MAmVJ^SQDlUw`gkRLpUuqGAp$vQMon? zu=bt9=FowdAH#RWV@*VJ^Qrk4QZIht%pY!<{@QoH__X-$>#wmXrT3h`_Y_-h?um42 zbfkar#7WP#P4`4~?(2x1Ieh}BhOW7KjhQIsGHl%c=l1K$Hwv4>Um314?AliSmhmMg zleUvy)%khDFBe@;*9VT4QzU5%l#^R!6Wki4AoPpXpu2 z1jpB3zDC5n;F}h;+qp^X16BxET1Q|6*fG>KCjr^1IZx9#HxGfH2Hfv|tWZd)8W;_D1M9A$%=gZGG>di z2zu4F2eqP58!rWkOIaRA@rpPdK0+RmuhJ;7d=kc&>uis~7T0Rs+y+rg4%8mP&C&#Y zmK~4lT8PE0i|Fbx63|-3!`eZ7JqR=dYKdF185dDwvYT#+mf?|bqg~BYQBkY-4Iz#} zw#H~Dywv;g-weAK3-Ifp(yeBX{bPg0d$=-&fw)<`)wj$jKa(F6_YlwT5%{oi`<9Sf zuWrV~`30<&`n-}M&FXSTe%}7^&&Kzz z7EE=;FF_~bxVhr0Ze{Hp>Y9o8(S`l}V{z5>G%Kf>wxv(R%eouids|bqDLSrI>R}Zw zEO#Paa;!aWb{RFW+g~uUj_ulcuRm)S_GoS)u`(D}3z}u*b=Rxjf_ywUQ`MTY>70(D z(kovP6T400s)dVjB0gK5Di%!xWfaQ3gjOuZcljPXr{sFmR^I-I@eIYe9maO`Yzf~6 zq8(#Lu)l~m~B=3)ZTmyXK J_kTG9{{@T=*3$q0 literal 0 HcmV?d00001