| Next revision | Previous revision |
| gdbs:protocol [2025/05/26 03:56] – created lars | gdbs:protocol [2025/05/31 07:21] (current) – [replies] lars |
|---|
| ====== gdb server protocol ====== | ====== gdb server protocol ====== |
| |
| | The gdb server protocol is used in a debug setup between gdb and the gdbserver. The gdbserver is the driver/software interface of the JATG/SWD probe. This allows the user to use an(optional) IDE with gdb to debug firmware running on a MCU. |
| |
| | <code> |
| | +------------------+ |
| | | User | |
| | +------------------+ |
| | | |
| | +------------------+ |
| | | IDE | |
| | +------------------+ |
| | | |
| | +------------------+ |
| | | gdb | |
| | +------------------+ |
| | | |
| | | <-- gdb server protocol is used here |
| | | |
| | +------------------+ |
| | | gdb server | |
| | +------------------+ |
| | | |
| | +------------------+ |
| | | JTAG / SWD probe | |
| | +------------------+ |
| | | |
| | +------------------+ |
| | | MCU | |
| | +------------------+ |
| | |
| | </code> |
| | |
| | The remote protocol is specified in [[https://sourceware.org/gdb/current/onlinedocs/gdb.html/Remote-Protocol.html|Appendix E]] of the [[https://sourceware.org/gdb/current/onlinedocs/gdb.html/index.html|gdb documentation]]. Wherever appropriate large parts of that documentation have been copied here. |
| | |
| | The protocol is used over a serial byte data stream. Examples are a serial port (UART/COM Port) or a TCP port. The data is exchanged over this channel in [[packets|packets]]. In this communication the gdb sends commands and the gdb server sends replies. |
| | |
| | In the documentation format strings everything [inside of square brackets] is optional and can be missing. |
| | |
| | ===== signals ===== |
| | |
| | [[signals|include/gdb/signals.h]] |
| | |
| | ===== commands ===== |
| | |
| | * '!' [[cmd_exclamation_mark|Enable extended mode]] **must be supported** |
| | * '?' [[cmd_question_mark|question mark]] |
| | * 'A' [[cmd_uc_a|A]] |
| | * 'b' [[cmd_lc_b|set baur rate]] **don't use** |
| | * 'B' [[cmd_uc_b|set or clear breakpoint]] **don't use** |
| | * 'bc' [[cmd_bc|backward continue]] |
| | * 'bs' [[cmd_bs|backward single step]] |
| | * 'c' [[cmd_lc_c|continue]] **must be supported** |
| | * 'C' [[cmd_uc_c|continue with signal]] |
| | * 'd' [[cmd_lc_d|toggle debug flag]] **don't use** |
| | * 'D' [[cmd_uc_d|detach]] |
| | * 'F' [[cmd_uc_f|file i/o]] |
| | * 'g' [[cmd_lc_g|read general register]] **must be supported** |
| | * 'G' [[cmd_uc_g|write general register]] **must be supported** |
| | * 'H' [[cmd_uc_h|select thread]] |
| | * 'i' [[cmd_lc_i|single clock step]] |
| | * 'I' [[cmd_uc_i|signal cycle step]] |
| | * 'k' [[cmd_lc_k|kill]] |
| | * 'm' [[cmd_lc_m|read memory]] **must be supported** |
| | * 'M' [[cmd_uc_m|write memory]] **must be supported** |
| | * 'p' [[cmd_lc_p|read register]] |
| | * 'P' [[cmd_uc_p|write register]] |
| | * 'QAgent' [[cmd_uc_q_agent|agent on/off]] |
| | * 'QAllow' [[cmd_uc_q_allow|allow operations]] |
| | * 'qC' [[cmd_lc_q_c|read current tread id]] |
| | * 'qCRC' [[cmd_lc_q_crc|CRC of memory region]] |
| | * 'QDisableRandomization' [[cmd_uc_q_disablerandomization|disable randomization of virtual addresses]] |
| | * 'QStartupWithShell' [[cmd_uc_q_startupwithshell|use shell]] |
| | * 'QEnvironmentHexEncoded' [[cmd_uc_q_environmenthexencoded|environment variables]] |
| | * 'QEnvironmentUnset' [[cmd_uc_q_environmentunset|unset environment variable]] |
| | * 'QEnvironmentReset' [[cmd_uc_q_environemnetreset|reset environment]] |
| | * 'QSetWorkingDir' [[cmd_uc_q_setworkingdirectory|set working directory]] |
| | * 'qfThreadInfo' [[cmd_lc_q_fthreadinfo|get active theads]] |
| | * 'qsThreadInfo' [[cmd_lc_q_sthreadinfo|get active theads]] |
| | * 'qGetTLSAddr' [[cmd_lc_q_gettlsaddr|get address of thread local storage]] |
| | * 'qGetTIBAddr' [[cmd_lc_q_gettibaddr|get the Windows OS specific thread information block]] |
| | * 'qL' [[cmd_lc_q_l|get thread infromation from RTOS]] |
| | * 'qMemTags' [[cmd_lc_q_memtags|get memory tags]] |
| | * 'qIsAddressTagged' [[cmd_lc_q_isaddresstagged|check if address is tagged]] |
| | * 'QMemTags' [[cmd_ucq_memtags|store memory tags]] |
| | * 'qOffsets' [[cmd_lc_q_offsets|get section offsets]] |
| | * 'qP' [[cmd_lcq_p|read thread id]] **don't use** |
| | * 'QNonStop' [[cmd_uc_q_nonstop|switch non stop mode]] |
| | * 'QCatchSyscalls' [[cmd_uc_q_catchsyscalls|switch catching syscalls]] |
| | * 'QPassSignals' [[cmd_uc_q_passsignals|which signals to pass]] |
| | * 'QProgramSignals' [[cmd_uc_q_programsignals|signals to target]] |
| | * 'QThreadEvents' [[cmd_uc_q_threadevents|switch reporting of thread events]] |
| | * 'QThreadOptions' [[cmd_uc_q_threadoptions|apply options]] |
| | * 'qRcmd' [[cmd_lc_q_rcmd|run command]] |
| | * 'qSearch' [[cmd_lc_q_search|search memory]] |
| | * 'QStartNoAckMode' [[cmd_uc_q_startnoackmode|stop sending acks]] |
| | * 'qSupported' [[cmd_lc_q_supported|tell gdbserver which features gdb supports]] |
| | * 'qSymbol' [[cmd_lc_q_symbol|tell gdb server that gdb can answere symbol requests]] |
| | * 'qTBuffer' [[cmd_lc_q_tbuffer|trace]] |
| | * 'QTBuffer' [[cmd_uc_q_tbuffer|trace]] |
| | * 'QTDisconnected' [[cmd_uc_q_tdisconnected|trace]] |
| | * 'QTDP' [[cmd_uc_q_tdp|trace]] |
| | * 'QTDPsrc' [[cmd_uc_q_tdpsrc|trace]] |
| | * 'QTDV' [[cmd_uc_q_tdv|trace]] |
| | * 'qTfP' [[cmd_uc_q_tfp|trace]] |
| | * 'qTfV' [[cmd_uc_q_tfv|trace]] |
| | * 'QTFrame' [[cmd_uc_q_tframe|trace]] |
| | * 'qTMinFTPILen' [[cmd_lc_q_tminftpilen|trace]] |
| | * 'qThreadExtraInfo' [[cmd_lc_q_threadExtraInfo|os decription for thread]] |
| | * ‘QTNotes’ [[cmd_uc_q_tnotes|trace]] |
| | * 'qTP' [[cmd_lc_q_tp|trace]] |
| | * 'QTSave' [[cmd_uc_q_tsave|trace]] |
| | * 'qTsP' [[cmd_lc_q_tsp|trace]] |
| | * 'qTsV' [[cmd_lc_q_tsv|trace]] |
| | * 'QTStart' [[cmd_uc_q_tstart|trace]] |
| | * 'QTStop' [[cmd_uc_q_tstop|trace]] |
| | * 'QTEnable' [[cmd_uc_q_tenable|trace]] |
| | * 'QTDisable' [[cmd_uc_q_tdisable|trace]] |
| | * 'QTinit' [[cmd_uc_q_tinit|trace]] |
| | * 'QTro' [[cmd_uc_q_tro|trace]] |
| | * 'qTStatus' [[cmd_lc_q_tstatus|trace]] |
| | * 'qTV' [[cmd_lc_q_tv|trace]] |
| | * 'qTfSTM' [[cmd_lc_q_tfstm|trace]] |
| | * 'qTsSTM' [[cmd_lc_q_tsstm|trace]] |
| | * 'qTSTMat' [[cmd_lc_q_tstmat|trace]] |
| | * 'qXfer' [[cmd_lc_q_xfer|read special area]] |
| | * 'qAttached' [[cmd_lc_q_attached|is attached?]] |
| | * 'Qbtrace' [[cmd_uc_q_btrace|enable branch tracing]] |
| | * 'Qbtrace-conf' [[cmd_uc_q_btrace_conf|configure branch trace]] |
| | * |
| | * 'r' [[cmd_lc_r|reset]] **don't use** |
| | * 'R' [[cmd_uc_r|restart program being debugged]] |
| | * 's' [[cmd_lc_s|single step]] **must be supported** |
| | * 'S' [[cmd_uc_s|signal single step]] |
| | * 't' [[cmd_lc_t|search backwards]] |
| | * 'T' [[cmd_uc_t|is thread alive]] |
| | * 'vAttach' [[cmd_vattach|attach to a new process]] |
| | * 'vCont' [[cmd_vcont|continue trhead]] **must be supported** |
| | * 'vCont?' [[cmd_vcont_qm|request supported actions of 'vCont']] |
| | * 'vCtrlC' [[cmd_vctrl|interrupt remote target]] |
| | * 'vFile' [[cmd_vfile|file operation on target file system]] |
| | * 'vFlashErase' [[cmd_vflasherase|erase flash]] |
| | * 'vFlashWrite' [[cmd_vflashwrite|write flash]] |
| | * 'vFlashDone' [[cmd_vflashdone|flash operations done]] |
| | * 'vKill' [[cmd_vkill|kill process]] |
| | * 'vMustReplyEmpty' [[cmd_vmustreplyempty|test unknown command reply]] |
| | * 'vRun' [[cmd_vrun|run program]] |
| | * 'vStopped' [[cmd_vstopped|stopped]] |
| | * 'x' [[cmd_lc_x|read memory]] |
| | * 'X' [[cmd_uc_x|write data to memory]] |
| | * 'z' [[cmd_lc_z|remove breakpoint]] |
| | * 'Z' [[cmd_uc_z|insert breakpoint]] |
| | |
| | ===== replies ===== |
| | * "" [[reply_empty|empty]] |
| | * "E" [[reply_e_xx|Error Hex]] |
| | * "E" [[reply_e_text|Error text]] |
| | * "S" [[reply_stop_uc_s|stopped because of Signal]] |
| | * "T" [[reply_stop_uc_t|stopped because of Signal + infos]] |
| | * "w" [[reply_stop_lc_w|thread exited]] |
| | * "W" [[reply_stop_uc_w|process exited]] |
| | * "X" [[reply_stop_uc_x|process terminated]] |
| | * "N" [[reply_stop_uc_n|no more threads]] |
| | * "O" [[reply_stop_uc_o|console output]] |
| | * "F" [[reply_stop_uc_f|host function call]] |
| | * [[notification_stop|notification stop]] |
| | |
| | |
| | ===== dictionary ===== |
| | |
| | ^ Word / Abbreviation ^ Explanation ^ |
| | | IDE | Integrated Development environment | |
| | | MCU | Micro Controller Unit | |
| | | addressable memory units | TODO | |
