{"id":16822226,"url":"https://github.com/mborgerson/gdbstub","last_synced_at":"2025-09-08T01:32:27.896Z","repository":{"id":38897474,"uuid":"56668666","full_name":"mborgerson/gdbstub","owner":"mborgerson","description":"Simple, single-file, dependency-free GDB stub that can be easily dropped in to your project.","archived":false,"fork":false,"pushed_at":"2022-10-07T05:08:29.000Z","size":83,"stargazers_count":214,"open_issues_count":5,"forks_count":23,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-10-14T11:02:43.832Z","etag":null,"topics":["debug","development","embedded","gdb","hacktoberfest","tools"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mborgerson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-20T08:14:04.000Z","updated_at":"2024-10-04T01:39:16.000Z","dependencies_parsed_at":"2022-08-19T04:12:03.501Z","dependency_job_id":null,"html_url":"https://github.com/mborgerson/gdbstub","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/mborgerson%2Fgdbstub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mborgerson%2Fgdbstub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mborgerson%2Fgdbstub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mborgerson%2Fgdbstub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mborgerson","download_url":"https://codeload.github.com/mborgerson/gdbstub/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232271900,"owners_count":18497768,"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":["debug","development","embedded","gdb","hacktoberfest","tools"],"created_at":"2024-10-13T11:02:48.223Z","updated_at":"2025-01-03T00:09:57.832Z","avatar_url":"https://github.com/mborgerson.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"gdbstub\n=======\nThis is a simple, single-file[^1] GDB stub library that can be easily dropped in to\nyour project to allow you to debug a target platform using GDB (or another\napplication which supports remote GDB targets). It has no library dependencies\n(such as libc) and requires just standard tools to build.\n\n[^1]: The main protocol bits and most architecture support is in a single\n      file: gdbstub.h. Some platform files might also be required depending on\n      your use case.\n\nProtocol\n--------\nCommunication between the stub and the debugger takes place via the [GDB\nRemote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html).\n\nUsage\n-----\nIn some `.c` file in your project:\n\n```c\n/* Define to enable bare metal x86 support, or define your own architecture */\n#define GDBSTUB_ARCH_X86\n\n/* Enable function definitions */\n#define GDBSTUB_IMPLEMENTATION\n\n#include \"gdbstub.h\"\n\nvoid _start(void) {\n\tdbg_sys_init(); /* Setup, wait for debugger on serial port  */\n}\n```\n\nSee `gdbstub.c` for example usage.\n\nArchitecture Support\n--------------------\n* `GDBSTUB_ARCH_MOCK`: A mock architecture for testing\n* `GDBSTUB_ARCH_X86`: Bare-metal x86 (32-bit). You'll also need interrupt handlers (so not .\n\nPorting\n-------\nThis was originally developed for embedded x86 systems, but it's fairly modular.\nWith a little effort, it can be easily ported to other platforms.\n\nI recommend copying the mock architecture implementation and adjusting it to fit\nyour platform's needs accordingly.\n\nPR's for other platforms are welcome!\n\nBuilding\n--------\nBy default, running `make` produces a `gdbstub` program. This is simply a stub\nfor a mock architecture (just a handful of registers and some memory) running\ninside a normal program that communicates over stdio.\n\nA stub intended for bare metal x86 machines can be built with `make ARCH=x86`.\nThis produces an ELF binary `gdbstub.elf` that will hook the current IDT\n(to support debug interrupts) and break.\n\nAdditionally, a simple flat binary `gdbstub.bin` is created from the ELF binary.\nThe intent for this flat binary is to be easily loaded into memory and jumped\nto.\n\nx86 Demo\n--------\nIn `gdbstub.c` there is a simple function that's used for demonstration and\ntesting. To use it, build the stub with:\n\n\t$ make ARCH=x86 INCLUDE_DEMO=1\n\nThen, to test the GDB stub out, launch an instance of the full-system emulator\n[QEMU](https://www.qemu.org/) as follows:\n\n\tqemu-system-i386 -serial tcp:127.0.0.1:1234,server -display none -kernel gdbstub.elf\n\nThis will launch QEMU, create a virtual machine with a virtual serial port that\ncan be connected to through local TCP port 1234, then load and run the stub\nexecutable inside the virtual machine.\n\nYou can then launch your local GDB client to get your GDB client to connect to\nthe virtual serial port and begin debugging the demo application:\n\n\t$ gdb\n\t(gdb) symbol-file gdbstub.elf\n\t(gdb) target remote 127.0.0.1:1234\n\t(gdb) b simple_loop\n\t(gdb) layout split\n\t(gdb) c\n\nFor example, step a couple of times and print out the value of `x`:\n\n\t(gdb) s 3\n\t(gdb) p/x x\n\t$1 = 0xdeadbeef\n\nLicense\n-------\nThis software is published under the terms of the MIT License. See `LICENSE.txt`\nfor full license.\n\nMatt Borgerson, 2016-2022\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmborgerson%2Fgdbstub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmborgerson%2Fgdbstub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmborgerson%2Fgdbstub/lists"}