{"id":13758706,"url":"https://github.com/flamewing/genesis-debugger","last_synced_at":"2025-05-10T08:30:40.673Z","repository":{"id":83536023,"uuid":"101474580","full_name":"flamewing/genesis-debugger","owner":"flamewing","description":"Debugger/error screen for Sega Genesis","archived":false,"fork":false,"pushed_at":"2021-06-27T19:06:46.000Z","size":79,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-03-20T11:30:39.378Z","etag":null,"topics":["68000","68k","asm","debugger","debugging-tool","disassembler","error-handler","m68000","m68k","m68k-disassembler","macros","stacktrace"],"latest_commit_sha":null,"homepage":null,"language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flamewing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-08-26T08:54:25.000Z","updated_at":"2023-06-13T04:05:07.000Z","dependencies_parsed_at":"2024-01-13T03:01:18.834Z","dependency_job_id":"3b43c424-e9e6-4908-8f18-74763f3df8be","html_url":"https://github.com/flamewing/genesis-debugger","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flamewing%2Fgenesis-debugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flamewing%2Fgenesis-debugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flamewing%2Fgenesis-debugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flamewing%2Fgenesis-debugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flamewing","download_url":"https://codeload.github.com/flamewing/genesis-debugger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253389493,"owners_count":21900767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["68000","68k","asm","debugger","debugging-tool","disassembler","error-handler","m68000","m68k","m68k-disassembler","macros","stacktrace"],"created_at":"2024-08-03T13:00:34.930Z","updated_at":"2025-05-10T08:30:39.120Z","avatar_url":"https://github.com/flamewing.png","language":"Assembly","readme":"# Readme\n\n## License\n\nThis uses a bsd 0-Clause License (0BSD). The TL;DR version is [here](https://tldrlegal.com/license/bsd-0-clause-license).\n\nBasically, you can use however you want, and you don't have to add credits, licenses, or anything to your hack.\n\nI only ask for the courtesy of giving some credit if you use it, but you are not forced to do it.\n\n## About\n\nThis is a general error debugging screen for the Sega Genesis witht he following features:\n\n- integrated disassembler, which is logically separated from the drawing code and from the debugger screen;\n- the code almost fully position-independent, meaning a binary blob can be made;\n- recovers more information from branches and many jumps, including dbCC opcodes;\n- brand new font with ASCII encoding, so you can roll your own;\n- handles all errors that can happen on a 68k, even if they cannot happen on a real Sega Genesis (such as bus errors);\n- has code that will make macro haters want to stay away.\n\nNote: If you use asm68k, you will not be able to build this. I use macros and functions to make the code more maintainable and readable, and asm68k sucks. Badly. And I am not saying this only in regards to macros -- I used to think it was only slightly worse than AS, but now I stand corrected: while I was working on a binary blob to support asm68k, I ran into a serious bug in it that caused it to misassemble the code generating a bad binary. If you use asm68k, you are on your own.\n\nThere is another warning I must give: I won't give support for anything but the Sonic Git disassemblies, so if you insist on using outdated disassemblies, you are on your own.\n\nWith those out of the way: first, let me explain how you will go about generating a listing file. In the previous version, I talked about map files; listing files are much better because they are generated much faster; the S2 and S\u0026K disassemblies disable it by default, though. In S2, you have to edit 3 places: one in s2.macrosetup.asm and the rest in s2.asm; so:\nin s2.macrosetup.asm: find this:\n\n```m68k\n        listing off\n```\n\nand change it to this:\n\n```m68k\n        listing purecode\n```\n\nYou can also use \"on\" or \"noskipped\" instead of \"purecode\", but I recommend using the latter. So now over to s2.asm, do the same twice. Now whenever you build your hack, a s2.lst file will also be generated.\n\nFor S\u0026K, you have to do the same once in sonic3k.macrosetup.asm, then in sonic3k.asm find this:\n\n```m68k\nZ80_Snd_Driver: include \"Sound/Z80 Sound Driver.asm\"\n```\n\nand change it to this:\n\n```m68k\nZ80_Snd_Driver: include \"Sound/Z80 Sound Driver.asm\"\n        listing purecode\n```\n\nNow that you are armed with listing files, time to hook up the new debugger! So go on ahead and grab it here. There are seven files in this archive; only 6 are needed for S2, the seventh is for compatibility with the S\u0026K disassembly. Extract these to your hack's main folder. You can move these around, as long as you edit the includes in the relevant files. You want to add these includes:\nFor S2:\n\n```m68k\n        include \"_inc/Debugger.asm\"\n```\n\nFor S\u0026K:\n\n```m68k\n        include \"skcompat.asm\"\n        include \"Debugger.asm\"\n```\n\nThese are enough to get everything working; he other files are pulled in automatically. Now the debugger is being assembled inside your hack; you want to setup the interrupt vector table to make use of it:\n\nIn S2: find \";Vectors:\" and replace the whole table with this:\n\n```m68k\n;Vectors:\n        dc.l System_Stack      , EntryPoint     , BusError         , AddressError   ;  4\n        dc.l IllegalInstrError , ZeroDivideError, CHKExceptionError, TRAPVError     ;  8\n        dc.l PrivilegeViolation, TraceError     , LineAEmulation   , LineFEmulation ; 12\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 16\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 20\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 24\n        dc.l SpuriousException , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 28\n        dc.l H_Int             , ErrorTrap      , V_Int            , ErrorTrap      ; 32\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 36\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 40\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 44\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 48\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 52\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 56\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 60\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 64\n```\n\nIn S\u0026K: find \"Vectors:\" and replace the whole table with this:\n\n```m68k\nVectors:\n        dc.l Vectors           , EntryPoint     , BusError         , AddressError   ;  4\n        dc.l IllegalInstrError , ZeroDivideError, CHKExceptionError, TRAPVError     ;  8\n        dc.l PrivilegeViolation, TraceError     , LineAEmulation   , LineFEmulation ; 12\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 16\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 20\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 24\n        dc.l SpuriousException , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 28\n        dc.l H_int_jump        , ErrorTrap      , V_int_jump       , ErrorTrap      ; 32\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 36\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 40\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 44\n        dc.l TrapVector        , TrapVector     , TrapVector       , TrapVector     ; 48\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 52\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 56\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 60\n        dc.l ErrorTrap         , ErrorTrap      , ErrorTrap        , ErrorTrap      ; 64\n```\n\nIf you try to assemble and you get errors, it is because you are using an older version of AS; get the new version and replace the ones you have. The Git repositories for the Community disassemblies already have this version, by the way.\n\nNow you just need to trigger an error to see it in action; but if you do that, you will notice that your name and e-mail are wrong; so open \"Debugger.asm\" and find the following lines:\n\n```m68k\nHackerName:     vtstring WHITE,\"Your name\"\nEMailmsg:       vtstring BLUE ,\"your.email@server.domain\"\n```\n\nExcept that the e-mail will not be in yellow and underlined, that is just the forum software being an ass. Anyway, supported colors are WHITE, RED, GREEN and BLUE; you can edit the text at will, but your name should not exceed 11 characters -- this is all the space available in the current setup. As the comment near this says, you can use any of the characters int he ASCII set.\n\nAnother thing to do is edit the value of the \"Revision\" constant in the same file -- this number can be used to uniquely identify the version in which the error happened, so you will know if you already fixed the error or not.\n\nWhen all is said and done, this is what you will see (using two manufactured examples):\n\n![Address error sample](img/address-error.png) ![Division by zero sample](img/div-by-zero.png)\n\nAs a bonus: since the code is logically separate, the disassembler can be used on its own; here is an example of a minimal disassembler that can be build using it:\n\n![Disassembler sample](img/disassembler-test.png)\n\nThis was done with this code:\n\n```m68k\nDisassemblyTest:\n        bsr.w   InitTerminal\n        lea     DrawTerminal(pc),a3\n        tellp.l -(sp)                                           ; Save end of buffer\n        setcursor       DisassemblyAlign,0\n\n.instr_loop:    shared .instr_loop\n        move.l  (sp),d0                                         ; Get end of screen buffer\n        vtchkp.l        d0                                      ; Is this after current position?\n        blo.w   .draw_terminal                                  ; Branch if not\n        tellp.l -(sp)                                           ; Save start of line\n        move.w  (a3)+,d5                                        ; Read instruction\n        lea     RewindStub(pc),a4                               ; Pointer to rts\n        bsr.w   Disassemble_Opcode\n        movea.l a2,a3                                           ; PC for next instruction\n        tellp.l d0                                              ; Save current position on buffer\n        seekset (sp)+                                           ; Seek back to old position\n\n.next_line:\n        seekp.l nCols                                           ; Advance it by one line\n        vtchkp.l        d0                                      ; Is this after current position on buffer?\n        bhs.s   .next_line                                      ; Branch if not\n        bra.s   .instr_loop\n;---------------------------------------------------------------------------------------\n.draw_terminal:\n        addq.w  #4,sp                                           ; Pop end of screen buffer from stack\n        bsr.w   DrawTerminal\n\n.error_trap:\n        nop\n        nop\n        bra.s   .error_trap\n; ===========================================================================\n```\n","funding_links":[],"categories":["Sega Genesis"],"sub_categories":["\u003ca name = \"retro-sega-genesis-source-codes\"\u003e\u003c/a\u003eSource codes"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflamewing%2Fgenesis-debugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflamewing%2Fgenesis-debugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflamewing%2Fgenesis-debugger/lists"}