====== 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. +------------------+ | User | +------------------+ | +------------------+ | IDE | +------------------+ | +------------------+ | gdb | +------------------+ | | <-- gdb server protocol is used here | +------------------+ | gdb server | +------------------+ | +------------------+ | JTAG / SWD probe | +------------------+ | +------------------+ | MCU | +------------------+ 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 |