1LLDB has added new GDB server packets to better support multi-threaded and 2remote debugging. Why? Normally you need to start the correct GDB and the 3correct GDB server when debugging. If you have mismatch, then things go wrong 4very quickly. LLDB makes extensive use of the GDB remote protocol and we 5wanted to make sure that the experience was a bit more dynamic where we can 6discover information about a remote target without having to know anything up 7front. We also ran into performance issues with the existing GDB remote 8protocol that can be overcome when using a reliable communications layer. 9Some packets improve performance, others allow for remote process launching 10(if you have an OS), and others allow us to dynamically figure out what 11registers a thread might have. Again with GDB, both sides pre-agree on how the 12registers will look (how many, their register number,name and offsets). We 13prefer to be able to dynamically determine what kind of architecture, OS and 14vendor we are debugging, as well as how things are laid out when it comes to 15the thread register contexts. Below are the details on the new packets we have 16added above and beyond the standard GDB remote protocol packets. 17 18//---------------------------------------------------------------------- 19// "QStartNoAckMode" 20// 21// BRIEF 22// Try to enable no ACK mode to skip sending ACKs and NACKs. 23// 24// PRIORITY TO IMPLEMENT 25// High. Any GDB remote server that can implement this should if the 26// connection is reliable. This improves packet throughput and increases 27// the performance of the connection. 28//---------------------------------------------------------------------- 29Having to send an ACK/NACK after every packet slows things down a bit, so we 30have a way to disable ACK packets to minimize the traffic for reliable 31communication interfaces (like sockets). Below GDB or LLDB will send this 32packet to try and disable ACKs. All lines that start with "send packet: " are 33from GDB/LLDB, and all lines that start with "read packet: " are from the GDB 34remote server: 35 36send packet: $QStartNoAckMode#b0 37read packet: + 38read packet: $OK#9a 39send packet: + 40 41 42 43//---------------------------------------------------------------------- 44// "A" - launch args packet 45// 46// BRIEF 47// Launch a program using the supplied arguments 48// 49// PRIORITY TO IMPLEMENT 50// Low. Only needed if the remote target wants to launch a target after 51// making a connection to a GDB server that isn't already connected to 52// an inferior process. 53//---------------------------------------------------------------------- 54 55We have added support for the "set program arguments" packet where we can 56start a connection to a remote server and then later supply the path to the 57executable and the arguments to use when executing: 58 59GDB remote docs for this: 60 61set program arguments(reserved) Aarglen,argnum,arg,... 62 63Where A is followed by the length in bytes of the hex encoded argument, 64followed by an argument integer, and followed by the ASCII characters 65converted into hex bytes foreach arg 66 67send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00 68read packet: $OK#00 69 70The above packet helps when you have remote debugging abilities where you 71could launch a process on a remote host, this isn't needed for bare board 72debugging. 73 74//---------------------------------------------------------------------- 75// "QEnvironment:NAME=VALUE" 76// 77// BRIEF 78// Setup the environment up for a new child process that will soon be 79// launched using the "A" packet. 80// 81// NB: key/value pairs are sent as-is so gdb-remote protocol meta characters 82// (e.g. '#' or '$') are not acceptable. If any non-printable or 83// metacharacters are present in the strings, QEnvironmentHexEncoded 84// should be used instead if it is available. If you don't want to 85// scan the environment strings before sending, prefer 86// the QEnvironmentHexEncoded packet over QEnvironment, if it is 87// available. 88// 89// PRIORITY TO IMPLEMENT 90// Low. Only needed if the remote target wants to launch a target after 91// making a connection to a GDB server that isn't already connected to 92// an inferior process. 93//---------------------------------------------------------------------- 94 95Both GDB and LLDB support passing down environment variables. Is it ok to 96respond with a "$#00" (unimplemented): 97 98send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00 99read packet: $OK#00 100 101This packet can be sent one or more times _prior_ to sending a "A" packet. 102 103//---------------------------------------------------------------------- 104// "QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)" 105// 106// BRIEF 107// Setup the environment up for a new child process that will soon be 108// launched using the "A" packet. 109// 110// The only difference between this packet and QEnvironment is that the 111// environment key-value pair is ascii hex encoded for transmission. 112// This allows values with gdb-remote metacharacters like '#' to be sent. 113// 114// PRIORITY TO IMPLEMENT 115// Low. Only needed if the remote target wants to launch a target after 116// making a connection to a GDB server that isn't already connected to 117// an inferior process. 118//---------------------------------------------------------------------- 119 120Both GDB and LLDB support passing down environment variables. Is it ok to 121respond with a "$#00" (unimplemented): 122 123send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00 124read packet: $OK#00 125 126This packet can be sent one or more times _prior_ to sending a "A" packet. 127 128//---------------------------------------------------------------------- 129// "QEnableErrorStrings" 130// 131// BRIEF 132// This packet enables reporting of Error strings in remote packet 133// replies from the server to client. If the server supports this 134// feature, it should send an OK response. The client can expect the 135// following error replies if this feature is enabled in the server -> 136// 137// EXX;AAAAAAAAA 138// 139// where AAAAAAAAA will be a hex encoded ASCII string. 140// XX is hex encoded byte number. 141// 142// It must be noted that even if the client has enabled reporting 143// strings in error replies, it must not expect error strings to all 144// error replies. 145// 146// PRIORITY TO IMPLEMENT 147// Low. Only needed if the remote target wants to provide strings that 148// are human readable along with an error code. 149//---------------------------------------------------------------------- 150 151send packet: $QEnableErrorStrings 152read packet: $OK#00 153 154//---------------------------------------------------------------------- 155// "QSetSTDIN:<ascii-hex-path>" 156// "QSetSTDOUT:<ascii-hex-path>" 157// "QSetSTDERR:<ascii-hex-path>" 158// 159// BRIEF 160// Setup where STDIN, STDOUT, and STDERR go prior to sending an "A" 161// packet. 162// 163// PRIORITY TO IMPLEMENT 164// Low. Only needed if the remote target wants to launch a target after 165// making a connection to a GDB server that isn't already connected to 166// an inferior process. 167//---------------------------------------------------------------------- 168 169When launching a program through the GDB remote protocol with the "A" packet, 170you might also want to specify where stdin/out/err go: 171 172QSetSTDIN:<ascii-hex-path> 173QSetSTDOUT:<ascii-hex-path> 174QSetSTDERR:<ascii-hex-path> 175 176These packets must be sent _prior_ to sending a "A" packet. 177 178//---------------------------------------------------------------------- 179// "QSetWorkingDir:<ascii-hex-path>" 180// 181// BRIEF 182// Set the working directory prior to sending an "A" packet. 183// 184// PRIORITY TO IMPLEMENT 185// Low. Only needed if the remote target wants to launch a target after 186// making a connection to a GDB server that isn't already connected to 187// an inferior process. 188//---------------------------------------------------------------------- 189 190Or specify the working directory: 191 192QSetWorkingDir:<ascii-hex-path> 193 194This packet must be sent _prior_ to sending a "A" packet. 195 196//---------------------------------------------------------------------- 197// "QSetDisableASLR:<bool>" 198// 199// BRIEF 200// Enable or disable ASLR on the next "A" packet. 201// 202// PRIORITY TO IMPLEMENT 203// Low. Only needed if the remote target wants to launch a target after 204// making a connection to a GDB server that isn't already connected to 205// an inferior process and if the target supports disabling ASLR 206// (Address space layout randomization). 207//---------------------------------------------------------------------- 208 209Or control if ASLR is enabled/disabled: 210 211send packet: QSetDisableASLR:1 212read packet: OK 213 214send packet: QSetDisableASLR:0 215read packet: OK 216 217This packet must be sent _prior_ to sending a "A" packet. 218 219//---------------------------------------------------------------------- 220// QListThreadsInStopReply 221// 222// BRIEF 223// Enable the threads: and thread-pcs: data in the question-mark packet 224// ("T packet") responses when the stub reports that a program has 225// stopped executing. 226// 227// PRIORITY TO IMPLEMENT 228// Performance. This is a performance benefit to lldb if the thread id's 229// and thread pc values are provided to lldb in the T stop packet -- if 230// they are not provided to lldb, lldb will likely need to send one to 231// two packets per thread to fetch the data at every private stop. 232//---------------------------------------------------------------------- 233 234send packet: QListThreadsInStopReply 235read packet: OK 236 237//---------------------------------------------------------------------- 238// jTraceStart: 239// 240// BRIEF 241// Packet for starting trace of type lldb::TraceType. The following 242// parameters should be appended to the packet formatted as a JSON 243// dictionary, where the schematic for the JSON dictionary in terms of 244// the recognized Keys is given below in the table. 245// Different tracing types could require different custom parameters. 246// Such custom tracing parameters if needed should be collectively 247// specified in a JSON dictionary and the dictionary can be appended 248// to this packet (as Value corresponding to "params"). Since sending 249// JSON data over gdb-remote protocol has certain limitations, binary 250// escaping convention should be used. 251// 252// Following is the list of parameters - 253// 254// Key Value (Integer) (O)Optional/ 255// (except params which should be a (M)Mandatory 256// JSON dictionary) 257// ========== ==================================================== 258// 259// type The type of trace to start (see M 260// lldb-enumerations for TraceType) 261// 262// buffersize The size of the buffer to allocate M 263// for trace gathering. 264// 265// threadid The id of the thread to start tracing O 266// on. 267// 268// metabuffersize The size of buffer to hold meta data O 269// used for decoding the trace data. 270// 271// params Any parameters that are specific to O 272// certain trace technologies should be 273// collectively specified as a JSON 274// dictionary 275// ========== ==================================================== 276// 277// Each tracing instance is identified by a trace id which is returned 278// as the reply to this packet. In case the tracing failed to begin an 279// error code along with a hex encoded ASCII message is returned 280// instead. 281//---------------------------------------------------------------------- 282 283send packet: jTraceStart:{"type":<type>,"buffersize":<buffersize>}] 284read packet: <trace id>/E<error code>;AAAAAAAAA 285 286//---------------------------------------------------------------------- 287// jTraceStop: 288// 289// BRIEF 290// Stop tracing instance with trace id <trace id>, of course trace 291// needs to be started before. The following parameters should be 292// formatted as a JSON dictionary to the packet. Since sending 293// JSON data over gdb-remote protocol has certain limitations, binary 294// escaping convention should be used. 295// 296// Following is the list of parameters - 297// 298// Key Value (Integer) (O)Optional/ 299// (M)Mandatory 300// ========== ==================================================== 301// 302// traceid The trace id of the tracing instance M 303// 304// threadid The id of the thread to stop tracing O 305// on. Since <trace id> could map to 306// multiple trace instances (in case it 307// maps to the complete process), the 308// threadid of a particular thread could 309// be appended as "threadid:<thread id>;" 310// to stop tracing on that thread. 311// ========== ==================================================== 312// 313// An OK response is sent in case of success else an error code along 314// with a hex encoded ASCII message is returned. 315//---------------------------------------------------------------------- 316 317send packet: jTraceStop:{"traceid":<trace id>}] 318read packet: <OK response>/E<error code>;AAAAAAAAA 319 320//---------------------------------------------------------------------- 321// jTraceBufferRead: 322// 323// BRIEF 324// Packet for reading the trace for tracing instance <trace id>, i.e the 325// id obtained from StartTrace API. The following parameters should be 326// formatted as a JSON dictionary to the packet. Since sending 327// JSON data over gdb-remote protocol has certain limitations, binary 328// escaping convention should be used. 329// 330// Following is the list of parameters - 331// 332// Key Value (Integer) (O)Optional/ 333// (M)Mandatory 334// ========== ==================================================== 335// traceid The trace id of the tracing instance M 336// 337// offset The offset to start reading the data M 338// from. 339// 340// buffersize The size of the data intended to read. M 341// 342// threadid The id of the thread to retrieve data O 343// from. 344// ========== ==================================================== 345// 346// The trace data is sent as raw binary data if the read was successful 347// else an error code along with a hex encoded ASCII message is sent. 348//---------------------------------------------------------------------- 349 350send packet: jTraceBufferRead:{"traceid":<trace id>,"offset":<byteoffset>,"buffersize":<byte_count>}] 351read packet: <binary trace data>/E<error code>;AAAAAAAAA 352 353//---------------------------------------------------------------------- 354// jTraceMetaRead: 355// 356// BRIEF 357// Similar Packet as above except it reads meta data. 358//---------------------------------------------------------------------- 359 360/---------------------------------------------------------------------- 361// jTraceConfigRead: 362// 363// BRIEF 364// Request the trace configuration for the tracing instance with id 365// <trace id>. 366// 367// Following is the list of parameters - 368// 369// Key Value (Integer) (O)Optional/ 370// (M)Mandatory 371// ========== ==================================================== 372// traceid The trace id of the tracing instance M 373// 374// threadid The id of the thread to obtain trace O 375// configuration from. Since <trace id> 376// could map to multiple trace instances 377// (in case it maps to the complete 378// process), the threadid of a particular 379// thread could be appended as 380// "threadid:<thread id>;" to obtain the 381// trace configuration of that thread. 382// ========== ==================================================== 383// 384// In the response packet the trace configuration is sent as text, 385// formatted as a JSON dictionary. Since sending JSON data over 386// gdb-remote protocol has certain limitations, binary escaping 387// convention is used. 388// In case the trace instance with the <trace id> was not found, an 389// error code along with a hex encoded ASCII message is returned. 390//---------------------------------------------------------------------- 391 392send packet: jTraceConfigRead:{"traceid":<trace id>} 393read packet: {"conf1":<conf1>,"conf2":<conf2>,"params":{"paramName":paramValue}]}];/E<error code>;AAAAAAAAA 394 395//---------------------------------------------------------------------- 396// "qRegisterInfo<hex-reg-id>" 397// 398// BRIEF 399// Discover register information from the remote GDB server. 400// 401// PRIORITY TO IMPLEMENT 402// High. Any target that can self describe its registers, should do so. 403// This means if new registers are ever added to a remote target, they 404// will get picked up automatically, and allows registers to change 405// depending on the actual CPU type that is used. 406// 407// NB: As of summer 2015, lldb can get register information from the 408// "qXfer:features:read:target.xml" FSF gdb standard register packet 409// where the stub provides register definitions in an XML file. 410// If qXfer:features:read:target.xml is supported, qRegisterInfo does 411// not need to be implemented. 412//---------------------------------------------------------------------- 413 414With LLDB, for register information, remote GDB servers can add 415support for the "qRegisterInfoN" packet where "N" is a zero based 416base16 register number that must start at zero and increase by one 417for each register that is supported. The response is done in typical 418GDB remote fashion where a series of "KEY:VALUE;" pairs are returned. 419An example for the x86_64 registers is included below: 420 421send packet: $qRegisterInfo0#00 422read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00 423send packet: $qRegisterInfo1#00 424read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00 425send packet: $qRegisterInfo2#00 426read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00 427send packet: $qRegisterInfo3#00 428read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00 429send packet: $qRegisterInfo4#00 430read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00 431send packet: $qRegisterInfo5#00 432read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00 433send packet: $qRegisterInfo6#00 434read packet: $name:rbp;alt-name:fp;bitsize:64;offset:48;encoding:uint;format:hex;set:General Purpose Registers;gcc:6;dwarf:6;generic:fp;#00 435send packet: $qRegisterInfo7#00 436read packet: $name:rsp;alt-name:sp;bitsize:64;offset:56;encoding:uint;format:hex;set:General Purpose Registers;gcc:7;dwarf:7;generic:sp;#00 437send packet: $qRegisterInfo8#00 438read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00 439send packet: $qRegisterInfo9#00 440read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00 441send packet: $qRegisterInfoa#00 442read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00 443send packet: $qRegisterInfob#00 444read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00 445send packet: $qRegisterInfoc#00 446read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00 447send packet: $qRegisterInfod#00 448read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00 449send packet: $qRegisterInfoe#00 450read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00 451send packet: $qRegisterInfof#00 452read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00 453send packet: $qRegisterInfo10#00 454read packet: $name:rip;alt-name:pc;bitsize:64;offset:128;encoding:uint;format:hex;set:General Purpose Registers;gcc:16;dwarf:16;generic:pc;#00 455send packet: $qRegisterInfo11#00 456read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00 457send packet: $qRegisterInfo12#00 458read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00 459send packet: $qRegisterInfo13#00 460read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00 461send packet: $qRegisterInfo14#00 462read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00 463send packet: $qRegisterInfo15#00 464read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00 465send packet: $qRegisterInfo16#00 466read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00 467send packet: $qRegisterInfo17#00 468read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00 469send packet: $qRegisterInfo18#00 470read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00 471send packet: $qRegisterInfo19#00 472read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00 473send packet: $qRegisterInfo1a#00 474read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00 475send packet: $qRegisterInfo1b#00 476read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00 477send packet: $qRegisterInfo1c#00 478read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00 479send packet: $qRegisterInfo1d#00 480read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00 481send packet: $qRegisterInfo1e#00 482read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00 483send packet: $qRegisterInfo1f#00 484read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00 485send packet: $qRegisterInfo20#00 486read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00 487send packet: $qRegisterInfo21#00 488read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00 489send packet: $qRegisterInfo22#00 490read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00 491send packet: $qRegisterInfo23#00 492read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00 493send packet: $qRegisterInfo24#00 494read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00 495send packet: $qRegisterInfo25#00 496read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00 497send packet: $qRegisterInfo26#00 498read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00 499send packet: $qRegisterInfo27#00 500read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00 501send packet: $qRegisterInfo28#00 502read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00 503send packet: $qRegisterInfo29#00 504read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00 505send packet: $qRegisterInfo2a#00 506read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00 507send packet: $qRegisterInfo2b#00 508read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00 509send packet: $qRegisterInfo2c#00 510read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00 511send packet: $qRegisterInfo2d#00 512read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00 513send packet: $qRegisterInfo2e#00 514read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00 515send packet: $qRegisterInfo2f#00 516read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00 517send packet: $qRegisterInfo30#00 518read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00 519send packet: $qRegisterInfo31#00 520read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00 521send packet: $qRegisterInfo32#00 522read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00 523send packet: $qRegisterInfo33#00 524read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00 525send packet: $qRegisterInfo34#00 526read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00 527send packet: $qRegisterInfo35#00 528read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00 529send packet: $qRegisterInfo36#00 530read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00 531send packet: $qRegisterInfo37#00 532read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00 533send packet: $qRegisterInfo38#00 534read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00 535send packet: $qRegisterInfo39#00 536read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00 537send packet: $qRegisterInfo3a#00 538read packet: $E45#00 539 540As we see above we keep making subsequent calls to the remote server to 541discover all registers by increasing the number appended to qRegisterInfo and 542we get a response back that is a series of "key=value;" strings. 543 544The offset: fields should not leave a gap anywhere in the g/G packet -- the 545register values should be appended one after another. For instance, if the 546register context for a thread looks like 547 548struct rctx { 549 uint32_t gpr1; // offset 0 550 uint32_t gpr2; // offset 4 551 uint32_t gpr3; // offset 8 552 uint64_t fp1; // offset 16 553}; 554 555You may end up with a 4-byte gap between gpr3 and fp1 on architectures 556that align values like this. The correct offset: value for fp1 is 12 - 557in the g/G packet fp1 will immediately follow gpr3, even though the 558in-memory thread structure has an empty 4 bytes for alignment between 559these two registers. 560 561The keys and values are detailed below: 562 563Key Value 564========== ================================================================ 565name The primary register name as a string ("rbp" for example) 566 567alt-name An alternate name for a register as a string ("fp" for example for 568 the above "rbp") 569 570bitsize Size in bits of a register (32, 64, etc). Base 10. 571 572offset The offset within the "g" and "G" packet of the register data for 573 this register. This is the byte offset once the data has been 574 transformed into binary, not the character offset into the g/G 575 packet. Base 10. 576 577encoding The encoding type of the register which must be one of: 578 579 uint (unsigned integer) 580 sint (signed integer) 581 ieee754 (IEEE 754 float) 582 vector (vector register) 583 584format The preferred format for display of this register. The value must 585 be one of: 586 587 binary 588 decimal 589 hex 590 float 591 vector-sint8 592 vector-uint8 593 vector-sint16 594 vector-uint16 595 vector-sint32 596 vector-uint32 597 vector-float32 598 vector-uint128 599 600set The register set name as a string that this register belongs to. 601 602gcc The GCC compiler registers number for this register (used for 603 EH frame and other compiler information that is encoded in the 604 executable files). The supplied number will be decoded like a 605 string passed to strtoul() with a base of zero, so the number 606 can be decimal, or hex if it is prefixed with "0x". 607 608 NOTE: If the compiler doesn't have a register number for this 609 register, this key/value pair should be omitted. 610 611dwarf The DWARF register number for this register that is used for this 612 register in the debug information. The supplied number will be decoded 613 like a string passed to strtoul() with a base of zero, so the number 614 can be decimal, or hex if it is prefixed with "0x". 615 616 NOTE: If the compiler doesn't have a register number for this 617 register, this key/value pair should be omitted. 618 619generic If the register is a generic register that most CPUs have, classify 620 it correctly so the debugger knows. Valid values are one of: 621 pc (a program counter register. for example "name=eip;" (i386), 622 "name=rip;" (x86_64), "name=r15;" (32 bit arm) would 623 include a "generic=pc;" key value pair) 624 sp (a stack pointer register. for example "name=esp;" (i386), 625 "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would 626 include a "generic=sp;" key value pair) 627 fp (a frame pointer register. for example "name=ebp;" (i386), 628 "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx 629 ABI) would include a "generic=fp;" key value pair) 630 ra (a return address register. for example "name=lr;" (32 bit ARM) 631 would include a "generic=ra;" key value pair) 632 fp (a CPU flags register. for example "name=eflags;" (i386), 633 "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM) 634 would include a "generic=flags;" key value pair) 635 arg1 - arg8 (specified for registers that contain function 636 arguments when the argument fits into a register) 637 638container-regs 639 The value for this key is a comma separated list of raw hex (optional 640 leading "0x") register numbers. 641 642 This specifies that this register is contained in other concrete 643 register values. For example "eax" is in the lower 32 bits of the 644 "rax" register value for x86_64, so "eax" could specify that it is 645 contained in "rax" by specifying the register number for "rax" (whose 646 register number is 0x00) 647 648 "container-regs:00;" 649 650 If a register is comprised of one or more registers, like "d0" is ARM 651 which is a 64 bit register, it might be made up of "s0" and "s1". If 652 the register number for "s0" is 0x20, and the register number of "s1" 653 is "0x21", the "container-regs" key/value pair would be: 654 655 "container-regs:20,21;" 656 657 This is handy for defining what GDB used to call "pseudo" registers. 658 These registers are never requested by LLDB via the register read 659 or write packets, the container registers will be requested on behalf 660 of this register. 661 662invalidate-regs 663 The value for this key is a comma separated list of raw hex (optional 664 leading "0x") register numbers. 665 666 This specifies which register values should be invalidated when this 667 register is modified. For example if modifying "eax" would cause "rax", 668 "eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15, 669 ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value 670 pair would be: 671 672 "invalidate-regs:0,15,25,35,39;" 673 674 If there is a single register that gets invalidated, then omit the comma 675 and just list a single register: 676 677 "invalidate-regs:0;" 678 679 This is handy when modifying a specific register can cause other 680 register values to change. For example, when debugging an ARM target, 681 modifying the CPSR register can cause the r8 - r14 and cpsr value to 682 change depending on if the mode has changed. 683 684//---------------------------------------------------------------------- 685// "qPlatform_shell" 686// 687// BRIEF 688// Run a command in a shell on the connected remote machine. 689// 690// PRIORITY TO IMPLEMENT 691// High. This command allows LLDB clients to run arbitrary shell 692// commands on a remote host. 693// 694/---------------------------------------------------------------------- 695 696The request consists of the command to be executed encoded in ASCII characters 697converted into hex bytes. 698 699The response to this packet consists of the letter F followed by the return code, 700followed by the signal number (or 0 if no signal was delivered), and escaped bytes 701of captured program output. 702 703Below is an example communication from a client sending an "ls -la" command: 704 705send packet: $qPlatform_shell:6c73202d6c61,00000002#ec 706read packet: $F,00000000,00000000,total 4736 707drwxrwxr-x 16 username groupname 4096 Aug 15 21:36 . 708drwxr-xr-x 17 username groupname 4096 Aug 10 16:39 .. 709-rw-rw-r-- 1 username groupname 73875 Aug 12 16:46 notes.txt 710drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp 711-rw-r--r-- 1 username groupname 2792 Aug 12 16:46 a.out 712-rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile 713 714//---------------------------------------------------------------------- 715// "qPlatform_mkdir" 716// 717// BRIEF 718// Creates a new directory on the connected remote machine. 719// 720// PRIORITY TO IMPLEMENT 721// Low. This command allows LLDB clients to create new directories on 722// a remote host. 723// 724/---------------------------------------------------------------------- 725 726Request: 727 qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path> 728 729Reply: 730 F<mkdir-return-code> 731 mkdir called successfully and returned with the given return code 732 Exx 733 An error occurred 734 735//---------------------------------------------------------------------- 736// "qPlatform_chmod" 737// 738// BRIEF 739// Change the permissions of a file on the connected remote machine. 740// 741// PRIORITY TO IMPLEMENT 742// Low. This command allows LLDB clients to change the permissions of 743// a file on the remote host. 744// 745/---------------------------------------------------------------------- 746 747Request: 748 qPlatform_chmod:<hex-file-mode>,<ascii-hex-path> 749 750Reply: 751 F<chmod-return-code> 752 chmod called successfully and returned with the given return code 753 Exx 754 An error occurred 755 756//---------------------------------------------------------------------- 757// "qHostInfo" 758// 759// BRIEF 760// Get information about the host we are remotely connected to. 761// 762// PRIORITY TO IMPLEMENT 763// High. This packet is usually very easy to implement and can help 764// LLDB select the correct plug-ins for the job based on the target 765// triple information that is supplied. 766//---------------------------------------------------------------------- 767 768LLDB supports a host info call that gets all sorts of details of the system 769that is being debugged: 770 771send packet: $qHostInfo#00 772read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00 773 774Key value pairs are one of: 775 776cputype: is a number that is the mach-o CPU type that is being debugged (base 10) 777cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged (base 10) 778triple: a string for the target triple (x86_64-apple-macosx) that can be used to specify arch + vendor + os in one entry 779vendor: a string for the vendor (apple), not needed if "triple" is specified 780ostype: a string for the OS being debugged (macosx, linux, freebsd, ios, watchos), not needed if "triple" is specified 781endian: is one of "little", "big", or "pdp" 782ptrsize: an unsigned number that represents how big pointers are in bytes on the debug target 783hostname: the hostname of the host that is running the GDB server if available 784os_build: a string for the OS build for the remote host as a string value 785os_kernel: a string describing the kernel version 786os_version: a version string that represents the current OS version (10.8.2) 787watchpoint_exceptions_received: one of "before" or "after" to specify if a watchpoint is triggered before or after the pc when it stops 788default_packet_timeout: an unsigned number that specifies the default timeout in seconds 789distribution_id: optional. For linux, specifies distribution id (e.g. ubuntu, fedora, etc.) 790osmajor: optional, specifies the major version number of the OS (e.g. for macOS 10.12.2, it would be 10) 791osminor: optional, specifies the minor version number of the OS (e.g. for macOS 10.12.2, it would be 12) 792ospatch: optional, specifies the patch level number of the OS (e.g. for macOS 10.12.2, it would be 2) 793addressing_bits: optional, specifies how many bits in addresses are 794 significant for addressing, base 10. If bits 38..0 795 in a 64-bit pointer are significant for addressing, 796 then the value is 39. This is needed on e.g. Aarch64 797 v8.3 ABIs that use pointer authentication, so lldb 798 knows which bits to clear/set to get the actual 799 addresses. 800 801//---------------------------------------------------------------------- 802// "qGDBServerVersion" 803// 804// BRIEF 805// Get version information about this implementation of the gdb-remote 806// protocol. 807// 808// PRIORITY TO IMPLEMENT 809// High. This packet is usually very easy to implement and can help 810// LLDB to work around bugs in a server's implementation when they 811// are found. 812//---------------------------------------------------------------------- 813 814The goal of this packet is to provide enough information about an 815implementation of the gdb-remote-protocol server that lldb can 816work around implementation problems that are discovered after the 817version has been released/deployed. The name and version number 818should be sufficiently unique that lldb can unambiguously identify 819the origin of the program (for instance, debugserver from lldb) and 820the version/submission number/patch level of the program - whatever 821is appropriate for your server implementation. 822 823The packet follows the key-value pair model, semicolon separated. 824 825send packet: $qGDBServerVersion#00 826read packet: $name:debugserver;version:310.2;#00 827 828Other clients may find other key-value pairs to be useful for identifying 829a gdb stub. Patch level, release name, build number may all be keys that 830better describe your implementation's version. 831Suggested key names: 832 833 name : the name of your remote server - "debugserver" is the lldb standard 834 implementation 835 836 version : identifies the version number of this server 837 838 patch_level : the patch level of this server 839 840 release_name : the name of this release, if your project uses names 841 842 build_number : if you use a build system with increasing build numbers, 843 this may be the right key name for your server 844 845 major_version : major version number 846 minor_version : minor version number 847 848//---------------------------------------------------------------------- 849// "qProcessInfo" 850// 851// BRIEF 852// Get information about the process we are currently debugging. 853// 854// PRIORITY TO IMPLEMENT 855// Medium. On systems which can launch multiple different architecture processes, 856// the qHostInfo may not disambiguate sufficiently to know what kind of 857// process is being debugged. 858// e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible, 859// and with Mach-O universal files, the executable file may contain both 32- and 860// 64-bit slices so it may be impossible to know until you're attached to a real 861// process to know what you're working with. 862// 863// All numeric fields return base-16 numbers without any "0x" prefix. 864//---------------------------------------------------------------------- 865 866An i386 process: 867 868send packet: $qProcessInfo#00 869read packet: $pid:42a8;parent-pid:42bf;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:7;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:4;#00 870 871An x86_64 process: 872 873send packet: $qProcessInfo#00 874read packet: $pid:d22c;parent-pid:d34d;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:1000007;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:8;#00 875 876Key value pairs include: 877 878pid: the process id 879parent-pid: the process of the parent process (often debugserver will become the parent when attaching) 880real-uid: the real user id of the process 881real-gid: the real group id of the process 882effective-uid: the effective user id of the process 883effective-gid: the effective group id of the process 884cputype: the Mach-O CPU type of the process (base 16) 885cpusubtype: the Mach-O CPU subtype of the process (base 16) 886ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) 887vendor: is a string that represents the vendor (apple) 888endian: is one of "little", "big", or "pdp" 889ptrsize: is a number that represents how big pointers are in bytes 890 891 892//---------------------------------------------------------------------- 893// "qShlibInfoAddr" 894// 895// BRIEF 896// Get an address where the dynamic linker stores information about 897// where shared libraries are loaded. 898// 899// PRIORITY TO IMPLEMENT 900// High if you have a dynamic loader plug-in in LLDB for your target 901// triple (see the "qHostInfo" packet) that can use this information. 902// Many times address load randomization can make it hard to detect 903// where the dynamic loader binary and data structures are located and 904// some platforms know, or can find out where this information is. 905// 906// Low if you have a debug target where all object and symbol files 907// contain static load addresses. 908//---------------------------------------------------------------------- 909 910LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each 911debugger as to where to find the dynamic loader information. For darwin 912binaries that run in user land this is the address of the "all_image_infos" 913structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO 914call. The result is returned as big endian hex bytes that are the address 915value: 916 917send packet: $qShlibInfoAddr#00 918read packet: $7fff5fc40040#00 919 920 921 922//---------------------------------------------------------------------- 923// "qThreadStopInfo<tid>" 924// 925// BRIEF 926// Get information about why a thread, whose ID is "<tid>", is stopped. 927// 928// PRIORITY TO IMPLEMENT 929// High if you need to support multi-threaded or multi-core debugging. 930// Many times one thread will hit a breakpoint and while the debugger 931// is in the process of suspending the other threads, other threads 932// will also hit a breakpoint. This packet allows LLDB to know why all 933// threads (live system debug) / cores (JTAG) in your program have 934// stopped and allows LLDB to display and control your program 935// correctly. 936//---------------------------------------------------------------------- 937 938LLDB tries to use the "qThreadStopInfo" packet which is formatted as 939"qThreadStopInfo%x" where %x is the hex thread ID. This requests information 940about why a thread is stopped. The response is the same as the stop reply 941packets and tells us what happened to the other threads. The standard GDB 942remote packets love to think that there is only _one_ reason that _one_ thread 943stops at a time. This allows us to see why all threads stopped and allows us 944to implement better multi-threaded debugging support. 945 946//---------------------------------------------------------------------- 947// "QThreadSuffixSupported" 948// 949// BRIEF 950// Try to enable thread suffix support for the 'g', 'G', 'p', and 'P' 951// packets. 952// 953// PRIORITY TO IMPLEMENT 954// High. Adding a thread suffix allows us to read and write registers 955// more efficiently and stops us from having to select a thread with 956// one packet and then read registers with a second packet. It also 957// makes sure that no errors can occur where the debugger thinks it 958// already has a thread selected (see the "Hg" packet from the standard 959// GDB remote protocol documentation) yet the remote GDB server actually 960// has another thread selected. 961//---------------------------------------------------------------------- 962 963When reading thread registers, you currently need to set the current 964thread, then read the registers. This is kind of cumbersome, so we added the 965ability to query if the remote GDB server supports adding a "thread:<tid>;" 966suffix to all packets that request information for a thread. To test if the 967remote GDB server supports this feature: 968 969send packet: $QThreadSuffixSupported#00 970read packet: OK 971 972If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a 973thread suffix. So to send a 'g' packet (read all register values): 974 975send packet: $g;thread:<tid>;#00 976read packet: .... 977 978send packet: $G;thread:<tid>;#00 979read packet: .... 980 981send packet: $p1a;thread:<tid>;#00 982read packet: .... 983 984send packet: $P1a=1234abcd;thread:<tid>;#00 985read packet: .... 986 987 988otherwise, without this you would need to always send two packets: 989 990send packet: $Hg<tid>#00 991read packet: .... 992send packet: $g#00 993read packet: .... 994 995We also added support for allocating and deallocating memory. We use this to 996allocate memory so we can run JITed code. 997 998//---------------------------------------------------------------------- 999// "_M<size>,<permissions>" 1000// 1001// BRIEF 1002// Allocate memory on the remote target with the specified size and 1003// permissions. 1004// 1005// PRIORITY TO IMPLEMENT 1006// High if you want LLDB to be able to JIT code and run that code. JIT 1007// code also needs data which is also allocated and tracked. 1008// 1009// Low if you don't support running JIT'ed code. 1010//---------------------------------------------------------------------- 1011 1012The allocate memory packet starts with "_M<size>,<permissions>". It returns a 1013raw big endian address value, or "" for unimplemented, or "EXX" for an error 1014code. The packet is formatted as: 1015 1016char packet[256]; 1017int packet_len; 1018packet_len = ::snprintf ( 1019 packet, 1020 sizeof(packet), 1021 "_M%zx,%s%s%s", 1022 (size_t)size, 1023 permissions & lldb::ePermissionsReadable ? "r" : "", 1024 permissions & lldb::ePermissionsWritable ? "w" : "", 1025 permissions & lldb::ePermissionsExecutable ? "x" : ""); 1026 1027You request a size and give the permissions. This packet does NOT need to be 1028implemented if you don't want to support running JITed code. The return value 1029is just the address of the newly allocated memory as raw big endian hex bytes. 1030 1031//---------------------------------------------------------------------- 1032// "_m<addr>" 1033// 1034// BRIEF 1035// Deallocate memory that was previously allocated using an allocate 1036// memory pack. 1037// 1038// PRIORITY TO IMPLEMENT 1039// High if you want LLDB to be able to JIT code and run that code. JIT 1040// code also needs data which is also allocated and tracked. 1041// 1042// Low if you don't support running JIT'ed code. 1043//---------------------------------------------------------------------- 1044 1045The deallocate memory packet is "_m<addr>" where you pass in the address you 1046got back from a previous call to the allocate memory packet. It returns "OK" 1047if the memory was successfully deallocated, or "EXX" for an error, or "" if 1048not supported. 1049 1050//---------------------------------------------------------------------- 1051// "qMemoryRegionInfo:<addr>" 1052// 1053// BRIEF 1054// Get information about the address range that contains "<addr>" 1055// 1056// PRIORITY TO IMPLEMENT 1057// Medium. This is nice to have, but it isn't necessary. It helps LLDB 1058// do stack unwinding when we branch into memory that isn't executable. 1059// If we can detect that the code we are stopped in isn't executable, 1060// then we can recover registers for stack frames above the current 1061// frame. Otherwise we must assume we are in some JIT'ed code (not JIT 1062// code that LLDB has made) and assume that no registers are available 1063// in higher stack frames. 1064//---------------------------------------------------------------------- 1065 1066We added a way to get information for a memory region. The packet is: 1067 1068 qMemoryRegionInfo:<addr> 1069 1070Where <addr> is a big endian hex address. The response is returned in a series 1071of tuples like the data returned in a stop reply packet. The currently valid 1072tuples to return are: 1073 1074 start:<start-addr>; // <start-addr> is a big endian hex address that is 1075 // the start address of the range that contains <addr> 1076 1077 size:<size>; // <size> is a big endian hex byte size of the address 1078 // of the range that contains <addr> 1079 1080 permissions:<permissions>; // <permissions> is a string that contains one 1081 // or more of the characters from "rwx" 1082 1083 name:<name>; // <name> is a hex encoded string that contains the name of 1084 // the memory region mapped at the given address. In case of 1085 // regions backed by a file it have to be the absolute path of 1086 // the file while for anonymous regions it have to be the name 1087 // associated to the region if that is available. 1088 1089 error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is 1090 // a hex encoded string value that 1091 // contains an error string 1092 1093If the address requested is not in a mapped region (e.g. we've jumped through 1094a NULL pointer and are at 0x0) currently lldb expects to get back the size 1095of the unmapped region -- that is, the distance to the next valid region. 1096For instance, with a macOS process which has nothing mapped in the first 10974GB of its address space, if we're asking about address 0x2, 1098 1099 qMemoryRegionInfo:2 1100 start:2;size:fffffffe; 1101 1102The lack of 'permissions:' indicates that none of read/write/execute are valid 1103for this region. 1104 1105//---------------------------------------------------------------------- 1106// "x" - Binary memory read 1107// 1108// Like the 'm' (read) and 'M' (write) packets, this is a partner to the 1109// 'X' (write binary data) packet, 'x'. 1110// 1111// It is called like 1112// 1113// xADDRESS,LENGTH 1114// 1115// where both ADDRESS and LENGTH are big-endian base 16 values. 1116// 1117// To test if this packet is available, send a addr/len of 0: 1118// 1119// x0,0 1120// 1121// and you will get an "OK" response. 1122// 1123// The reply will be the data requested in 8-bit binary data format. 1124// The standard quoting is applied to the payload -- characters 1125// } # $ * 1126// will all be escaped with '}' (0x7d) character and then XOR'ed with 0x20. 1127// 1128// A typical use to read 512 bytes at 0x1000 would look like 1129// 1130// x0x1000,0x200 1131// 1132// The "0x" prefixes are optional - like most of the gdb-remote packets, 1133// omitting them will work fine; these numbers are always base 16. 1134// 1135// The length of the payload is not provided. A reliable, 8-bit clean, 1136// transport layer is assumed. 1137//---------------------------------------------------------------------- 1138 1139//---------------------------------------------------------------------- 1140// Detach and stay stopped: 1141// 1142// We extended the "D" packet to specify that the monitor should keep the 1143// target suspended on detach. The normal behavior is to resume execution 1144// on detach. We will send: 1145// 1146// qSupportsDetachAndStayStopped: 1147// 1148// to query whether the monitor supports the extended detach, and if it does, 1149// when we want the monitor to detach but not resume the target, we will 1150// send: 1151// 1152// D1 1153// 1154// In any case, if we want the normal detach behavior we will just send: 1155// 1156// D 1157//---------------------------------------------------------------------- 1158 1159//---------------------------------------------------------------------- 1160// QSaveRegisterState 1161// QSaveRegisterState;thread:XXXX; 1162// 1163// BRIEF 1164// The QSaveRegisterState packet tells the remote debugserver to save 1165// all registers and return a non-zero unique integer ID that 1166// represents these save registers. If thread suffixes are enabled the 1167// second form of this packet is used, otherwise the first form is 1168// used. This packet is called prior to executing an expression, so 1169// the remote GDB server should do anything it needs to in order to 1170// ensure the registers that are saved are correct. On macOS this 1171// involves calling "thread_abort_safely(mach_port_t thread)" to 1172// ensure we get the correct registers for a thread in case it is 1173// currently having code run on its behalf in the kernel. 1174// 1175// RESPONSE 1176// unsigned - The save_id result is a non-zero unsigned integer value 1177// that can be passed back to the GDB server using a 1178// QRestoreRegisterState packet to restore the registers 1179// one time. 1180// "EXX" - or an error code in the form of EXX where XX is a 1181// hex error code. 1182// 1183// PRIORITY TO IMPLEMENT 1184// Low, this is mostly a convenience packet to avoid having to send all 1185// registers via a g packet. It should only be implemented if support 1186// for the QRestoreRegisterState is added. 1187//---------------------------------------------------------------------- 1188 1189//---------------------------------------------------------------------- 1190// QRestoreRegisterState:<save_id> 1191// QRestoreRegisterState:<save_id>;thread:XXXX; 1192// 1193// BRIEF 1194// The QRestoreRegisterState packet tells the remote debugserver to 1195// restore all registers using the "save_id" which is an unsigned 1196// integer that was returned from a previous call to 1197// QSaveRegisterState. The restoration process can only be done once 1198// as the data backing the register state will be freed upon the 1199// completion of the QRestoreRegisterState command. 1200// 1201// If thread suffixes are enabled the second form of this packet is 1202// used, otherwise the first form is used. 1203// 1204// RESPONSE 1205// "OK" - if all registers were successfully restored 1206// "EXX" - for any errors 1207// 1208// PRIORITY TO IMPLEMENT 1209// Low, this is mostly a convenience packet to avoid having to send all 1210// registers via a g packet. It should only be implemented if support 1211// for the QSaveRegisterState is added. 1212//---------------------------------------------------------------------- 1213 1214//---------------------------------------------------------------------- 1215// qFileLoadAddress:<file_path> 1216// 1217// BRIEF 1218// Get the load address of a memory mapped file. 1219// The load address is defined as the address of the first memory 1220// region what contains data mapped from the specified file. 1221// 1222// RESPONSE 1223// <unsigned-hex64> - Load address of the file in big endian encoding 1224// "E01" - the requested file isn't loaded 1225// "EXX" - for any other errors 1226// 1227// PRIORITY TO IMPLEMENT 1228// Low, required if dynamic linker don't fill in the load address of 1229// some object file in the rendezvous data structure. 1230//---------------------------------------------------------------------- 1231 1232//---------------------------------------------------------------------- 1233// qModuleInfo:<module_path>;<arch triple> 1234// 1235// BRIEF 1236// Get information for a module by given module path and architecture. 1237// 1238// RESPONSE 1239// "(uuid|md5):...;triple:...;file_offset:...;file_size...;" 1240// "EXX" - for any errors 1241// 1242// PRIORITY TO IMPLEMENT 1243// Optional, required if dynamic loader cannot fetch module's information like 1244// UUID directly from inferior's memory. 1245//---------------------------------------------------------------------- 1246 1247//---------------------------------------------------------------------- 1248// jModulesInfo:[{"file":"...",triple:"..."}, ...] 1249// 1250// BRIEF 1251// Get information for a list of modules by given module path and 1252// architecture. 1253// 1254// RESPONSE 1255// A JSON array of dictionaries containing the following keys: uuid, 1256// triple, file_path, file_offset, file_size. The meaning of the fields 1257// is the same as in the qModuleInfo packet. The server signals the 1258// failure to retrieve the module info for a file by ommiting the 1259// corresponding array entry from the response. The server may also 1260// include entries the client did not ask for, if it has reason to 1261// the modules will be interesting to the client. 1262// 1263// PRIORITY TO IMPLEMENT 1264// Optional. If not implemented, qModuleInfo packet will be used, which 1265// may be slower if the target contains a large number of modules and 1266// the communication link has a non-negligible latency. 1267//---------------------------------------------------------------------- 1268 1269//---------------------------------------------------------------------- 1270// Stop reply packet extensions 1271// 1272// BRIEF 1273// This section describes some of the additional information you can 1274// specify in stop reply packets that help LLDB to know more detailed 1275// information about your threads. 1276// 1277// DESCRIPTION 1278// Standard GDB remote stop reply packets are reply packets sent in 1279// response to a packet that made the program run. They come in the 1280// following forms: 1281// 1282// "SAA" 1283// "S" means signal and "AA" is a hex signal number that describes why 1284// the thread or stopped. It doesn't specify which thread, so the "T" 1285// packet is recommended to use instead of the "S" packet. 1286// 1287// "TAAkey1:value1;key2:value2;..." 1288// "T" means a thread stopped due to a unix signal where "AA" is a hex 1289// signal number that describes why the program stopped. This is 1290// followed by a series of key/value pairs: 1291// - If key is a hex number, it is a register number and value is 1292// the hex value of the register in debuggee endian byte order. 1293// - If key == "thread", then the value is the big endian hex 1294// thread-id of the stopped thread. 1295// - If key == "core", then value is a hex number of the core on 1296// which the stop was detected. 1297// - If key == "watch" or key == "rwatch" or key == "awatch", then 1298// value is the data address in big endian hex 1299// - If key == "library", then value is ignore and "qXfer:libraries:read" 1300// packets should be used to detect any newly loaded shared libraries 1301// 1302// "WAA" 1303// "W" means the process exited and "AA" is the exit status. 1304// 1305// "XAA" 1306// "X" means the process exited and "AA" is signal that caused the program 1307// to exit. 1308// 1309// "O<ascii-hex-string>" 1310// "O" means STDOUT has data that was written to its console and is 1311// being delivered to the debugger. This packet happens asynchronously 1312// and the debugger is expected to continue to wait for another stop reply 1313// packet. 1314// 1315// LLDB EXTENSIONS 1316// 1317// We have extended the "T" packet to be able to also understand the 1318// following keys and values: 1319// 1320// KEY VALUE DESCRIPTION 1321// =========== ======== ================================================ 1322// "metype" unsigned mach exception type (the value of the EXC_XXX enumerations) 1323// as an unsigned integer. For targets with mach 1324// kernels only. 1325// 1326// "mecount" unsigned mach exception data count as an unsigned integer 1327// For targets with mach kernels only. 1328// 1329// "medata" unsigned There should be "mecount" of these and it is the data 1330// that goes along with a mach exception (as an unsigned 1331// integer). For targets with mach kernels only. 1332// 1333// "name" string The name of the thread as a plain string. The string 1334// must not contain an special packet characters or 1335// contain a ':' or a ';'. Use "hexname" if the thread 1336// name has special characters. 1337// 1338// "hexname" ascii-hex An ASCII hex string that contains the name of the thread 1339// 1340// "qaddr" hex Big endian hex value that contains the libdispatch 1341// queue address for the queue of the thread. 1342// 1343// "reason" enum The enumeration must be one of: 1344// "trace" the program stopped after a single instruction 1345// was executed on a core. Usually done when single 1346// stepping past a breakpoint 1347// "breakpoint" a breakpoint set using a 'z' packet was hit. 1348// "trap" stopped due to user interruption 1349// "signal" stopped due to an actual unix signal, not 1350// just the debugger using a unix signal to keep 1351// the GDB remote client happy. 1352// "watchpoint". Should be used in conjunction with 1353// the "watch"/"rwatch"/"awatch" key value pairs. 1354// "exception" an exception stop reason. Use with 1355// the "description" key/value pair to describe the 1356// exceptional event the user should see as the stop 1357// reason. 1358// "description" ascii-hex An ASCII hex string that contains a more descriptive 1359// reason that the thread stopped. This is only needed 1360// if none of the key/value pairs are enough to 1361// describe why something stopped. 1362// 1363// "threads" comma-sep-base16 A list of thread ids for all threads (including 1364// the thread that we're reporting as stopped) that 1365// are live in the process right now. lldb may 1366// request that this be included in the T packet via 1367// the QListThreadsInStopReply packet earlier in 1368// the debug session. 1369// 1370// Example: 1371// threads:63387,633b2,63424,63462,63486; 1372// 1373// "thread-pcs" comma-sep-base16 A list of pc values for all threads that currently 1374// exist in the process, including the thread that 1375// this T packet is reporting as stopped. 1376// This key-value pair will only be emitted when the 1377// "threads" key is already included in the T packet. 1378// The pc values correspond to the threads reported 1379// in the "threads" list. The number of pcs in the 1380// "thread-pcs" list will be the same as the number of 1381// threads in the "threads" list. 1382// lldb may request that this be included in the T 1383// packet via the QListThreadsInStopReply packet 1384// earlier in the debug session. 1385// 1386// Example: 1387// thread-pcs:dec14,2cf872b0,2cf8681c,2d02d68c,2cf716a8; 1388// 1389// BEST PRACTICES: 1390// Since register values can be supplied with this packet, it is often useful 1391// to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate 1392// packets don't need to be sent to read each of these registers from each 1393// thread. 1394// 1395// If a thread is stopped for no reason (like just because another thread 1396// stopped, or because when one core stops all cores should stop), use a 1397// "T" packet with "00" as the signal number and fill in as many key values 1398// and registers as possible. 1399// 1400// LLDB likes to know why a thread stopped since many thread control 1401// operations like stepping over a source line, actually are implemented 1402// by running the process multiple times. If a breakpoint is hit while 1403// trying to step over a source line and LLDB finds out that a breakpoint 1404// is hit in the "reason", we will know to stop trying to do the step 1405// over because something happened that should stop us from trying to 1406// do the step. If we are at a breakpoint and we disable the breakpoint 1407// at the current PC and do an instruction single step, knowing that 1408// we stopped due to a "trace" helps us know that we can continue 1409// running versus stopping due to a "breakpoint" (if we have two 1410// breakpoint instruction on consecutive instructions). So the more info 1411// we can get about the reason a thread stops, the better job LLDB can 1412// do when controlling your process. A typical GDB server behavior is 1413// to send a SIGTRAP for breakpoints _and_ also when instruction single 1414// stepping, in this case the debugger doesn't really know why we 1415// stopped and it can make it hard for the debugger to control your 1416// program correctly. What if a real SIGTRAP was delivered to a thread 1417// while we were trying to single step? We wouldn't know the difference 1418// with a standard GDB remote server and we could do the wrong thing. 1419// 1420// PRIORITY TO IMPLEMENT 1421// High. Having the extra information in your stop reply packets makes 1422// your debug session more reliable and informative. 1423//---------------------------------------------------------------------- 1424 1425 1426//---------------------------------------------------------------------- 1427// PLATFORM EXTENSION - for use as a GDB remote platform 1428//---------------------------------------------------------------------- 1429// "qfProcessInfo" 1430// "qsProcessInfo" 1431// 1432// BRIEF 1433// Get the first process info (qfProcessInfo) or subsequent process 1434// info (qsProcessInfo) for one or more processes on the remote 1435// platform. The first call gets the first match and subsequent calls 1436// to qsProcessInfo gets the subsequent matches. Return an error EXX, 1437// where XX are two hex digits, when no more matches are available. 1438// 1439// PRIORITY TO IMPLEMENT 1440// Required. The qfProcessInfo packet can be followed by a ':' and 1441// some key value pairs. The key value pairs in the command are: 1442// 1443// KEY VALUE DESCRIPTION 1444// =========== ======== ================================================ 1445// "name" ascii-hex An ASCII hex string that contains the name of 1446// the process that will be matched. 1447// "name_match" enum One of: "equals", "starts_with", "ends_with", 1448// "contains" or "regex" 1449// "pid" integer A string value containing the decimal process ID 1450// "parent_pid" integer A string value containing the decimal parent 1451// process ID 1452// "uid" integer A string value containing the decimal user ID 1453// "gid" integer A string value containing the decimal group ID 1454// "euid" integer A string value containing the decimal effective user ID 1455// "egid" integer A string value containing the decimal effective group ID 1456// "all_users" bool A boolean value that specifies if processes should 1457// be listed for all users, not just the user that the 1458// platform is running as 1459// "triple" string An ASCII triple string ("x86_64", 1460// "x86_64-apple-macosx", "armv7-apple-ios") 1461// "args" string A string value containing the process arguments 1462// separated by the character '-', where each argument is 1463// hex-encoded. It includes argv[0]. 1464// 1465// The response consists of key/value pairs where the key is separated from the 1466// values with colons and each pair is terminated with a semi colon. For a list 1467// of the key/value pairs in the response see the "qProcessInfoPID" packet 1468// documentation. 1469// 1470// Sample packet/response: 1471// send packet: $qfProcessInfo#00 1472// read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00 1473// send packet: $qsProcessInfo#00 1474// read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:x86_64-apple-macosx;#00 1475// send packet: $qsProcessInfo#00 1476// read packet: $E04#00 1477//---------------------------------------------------------------------- 1478 1479 1480//---------------------------------------------------------------------- 1481// PLATFORM EXTENSION - for use as a GDB remote platform 1482//---------------------------------------------------------------------- 1483// "qLaunchGDBServer" 1484// 1485// BRIEF 1486// Have the remote platform launch a GDB server. 1487// 1488// PRIORITY TO IMPLEMENT 1489// Required. The qLaunchGDBServer packet must be followed by a ':' and 1490// some key value pairs. The key value pairs in the command are: 1491// 1492// KEY VALUE DESCRIPTION 1493// =========== ======== ================================================ 1494// "port" integer A string value containing the decimal port ID or 1495// zero if the port should be bound and returned 1496// 1497// "host" integer The host that connections should be limited to 1498// when the GDB server is connected to. 1499// 1500// The response consists of key/value pairs where the key is separated from the 1501// values with colons and each pair is terminated with a semi colon. 1502// 1503// Sample packet/response: 1504// send packet: $qLaunchGDBServer:port:0;host:lldb.apple.com;#00 1505// read packet: $pid:60025;port:50776;#00 1506// 1507// The "pid" key/value pair is only specified if the remote platform launched 1508// a separate process for the GDB remote server and can be omitted if no 1509// process was separately launched. 1510// 1511// The "port" key/value pair in the response lets clients know what port number 1512// to attach to in case zero was specified as the "port" in the sent command. 1513//---------------------------------------------------------------------- 1514 1515 1516//---------------------------------------------------------------------- 1517// PLATFORM EXTENSION - for use as a GDB remote platform 1518//---------------------------------------------------------------------- 1519// "qProcessInfoPID:PID" 1520// 1521// BRIEF 1522// Have the remote platform get detailed information on a process by 1523// ID. PID is specified as a decimal integer. 1524// 1525// PRIORITY TO IMPLEMENT 1526// Optional. 1527// 1528// The response consists of key/value pairs where the key is separated from the 1529// values with colons and each pair is terminated with a semi colon. 1530// 1531// The key value pairs in the response are: 1532// 1533// KEY VALUE DESCRIPTION 1534// =========== ======== ================================================ 1535// "pid" integer Process ID as a decimal integer string 1536// "ppid" integer Parent process ID as a decimal integer string 1537// "uid" integer A string value containing the decimal user ID 1538// "gid" integer A string value containing the decimal group ID 1539// "euid" integer A string value containing the decimal effective user ID 1540// "egid" integer A string value containing the decimal effective group ID 1541// "name" ascii-hex An ASCII hex string that contains the name of the process 1542// "triple" string A target triple ("x86_64-apple-macosx", "armv7-apple-ios") 1543// 1544// Sample packet/response: 1545// send packet: $qProcessInfoPID:60050#00 1546// read packet: $pid:60050;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00 1547//---------------------------------------------------------------------- 1548 1549//---------------------------------------------------------------------- 1550// "vAttachName" 1551// 1552// BRIEF 1553// Same as vAttach, except instead of a "pid" you send a process name. 1554// 1555// PRIORITY TO IMPLEMENT 1556// Low. Only needed for "process attach -n". If the packet isn't supported 1557// then "process attach -n" will fail gracefully. So you need only to support 1558// it if attaching to a process by name makes sense for your environment. 1559//---------------------------------------------------------------------- 1560 1561//---------------------------------------------------------------------- 1562// "vAttachWait" 1563// 1564// BRIEF 1565// Same as vAttachName, except that the stub should wait for the next instance 1566// of a process by that name to be launched and attach to that. 1567// 1568// PRIORITY TO IMPLEMENT 1569// Low. Only needed to support "process attach -w -n" which will fail 1570// gracefully if the packet is not supported. 1571//---------------------------------------------------------------------- 1572 1573//---------------------------------------------------------------------- 1574// "qAttachOrWaitSupported" 1575// 1576// BRIEF 1577// This is a binary "is it supported" query. Return OK if you support 1578// vAttachOrWait 1579// 1580// PRIORITY TO IMPLEMENT 1581// Low. This is required if you support vAttachOrWait, otherwise no support 1582// is needed since the standard "I don't recognize this packet" response 1583// will do the right thing. 1584//---------------------------------------------------------------------- 1585 1586//---------------------------------------------------------------------- 1587// "vAttachOrWait" 1588// 1589// BRIEF 1590// Same as vAttachWait, except that the stub will attach to a process 1591// by name if it exists, and if it does not, it will wait for a process 1592// of that name to appear and attach to it. 1593// 1594// PRIORITY TO IMPLEMENT 1595// Low. Only needed to implement "process attach -w -i false -n". If 1596// you don't implement it but do implement -n AND lldb can somehow get 1597// a process list from your device, it will fall back on scanning the 1598// process list, and sending vAttach or vAttachWait depending on 1599// whether the requested process exists already. This is racy, 1600// however, so if you want to support this behavior it is better to 1601// support this packet. 1602//---------------------------------------------------------------------- 1603 1604//---------------------------------------------------------------------- 1605// "jThreadExtendedInfo" 1606// 1607// BRIEF 1608// This packet, which takes its arguments as JSON and sends its reply as 1609// JSON, allows the gdb remote stub to provide additional information 1610// about a given thread. 1611// 1612// PRIORITY TO IMPLEMENT 1613// Low. This packet is only needed if the gdb remote stub wants to 1614// provide interesting additional information about a thread for the 1615// user. 1616// 1617// This packet takes its arguments in JSON form ( http://www.json.org ). 1618// At a minimum, a thread must be specified, for example: 1619// 1620// jThreadExtendedInfo:{"thread":612910} 1621// 1622// Because this is a JSON string, the thread number is provided in base10. 1623// Additional key-value pairs may be provided by lldb to the gdb remote 1624// stub. For instance, on some versions of macOS, lldb can read offset 1625// information out of the system libraries. Using those offsets, debugserver 1626// is able to find the Thread Specific Address (TSD) for a thread and include 1627// that in the return information. So lldb will send these additional fields 1628// like so: 1629// 1630// jThreadExtendedInfo:{"plo_pthread_tsd_base_address_offset":0,"plo_pthread_tsd_base_offset":224,"plo_pthread_tsd_entry_size":8,"thread":612910} 1631// 1632// There are no requirements for what is included in the response. A simple 1633// reply on a OS X Yosemite / iOS 8 may include the pthread_t value, the 1634// Thread Specific Data (TSD) address, the dispatch_queue_t value if the thread 1635// is associated with a GCD queue, and the requested Quality of Service (QoS) 1636// information about that thread. For instance, a reply may look like: 1637// 1638// {"tsd_address":4371349728,"requested_qos":{"enum_value":33,"constant_name":"QOS_CLASS_USER_INTERACTIVE","printable_name":"User Interactive"},"pthread_t":4371349504,"dispatch_queue_t":140735087127872} 1639// 1640// tsd_address, pthread_t, and dispatch_queue_t are all simple key-value pairs. 1641// The JSON standard requires that numbers be expressed in base 10 - so all of 1642// these are. requested_qos is a dictionary with three key-value pairs in it - 1643// so the UI layer may choose the form most appropriate for displaying to the user. 1644// 1645// Sending JSON over gdb-remote protocol introduces some problems. We may be 1646// sending strings with arbitrary contents in them, including the '#', '$', and '*' 1647// characters that have special meaning in gdb-remote protocol and cannot occur 1648// in the middle of the string. The standard solution for this would be to require 1649// ascii-hex encoding of all strings, or ascii-hex encode the entire JSON payload. 1650// 1651// Instead, the binary escaping convention is used for JSON data. This convention 1652// (e.g. used for the X packet) says that if '#', '$', '*', or '}' are to occur in 1653// the payload, the character '}' (0x7d) is emitted, then the metacharacter is emitted 1654// xor'ed by 0x20. The '}' character occurs in every JSON payload at least once, and 1655// '}' ^ 0x20 happens to be ']' so the raw packet characters for a request will look 1656// like 1657// 1658// jThreadExtendedInfo:{"thread":612910}] 1659// 1660// on the wire. 1661//---------------------------------------------------------------------- 1662 1663//---------------------------------------------------------------------- 1664// "QEnableCompression" 1665// 1666// BRIEF 1667// This packet enables compression of the packets that the debug stub sends to lldb. 1668// If the debug stub can support compression, it indictes this in the reply of the 1669// "qSupported" packet. e.g. 1670// LLDB SENDS: qSupported:xmlRegisters=i386,arm,mips 1671// STUB REPLIES: qXfer:features:read+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;DefaultCompressionMinSize=384 1672// 1673// If lldb knows how to use any of these compression algorithms, it can ask that this 1674// compression mode be enabled. It may optionally change the minimum packet size 1675// where compression is used. Typically small packets do not benefit from compression, 1676// as well as compression headers -- compression is most beneficial with larger packets. 1677// 1678// QEnableCompression:type:zlib-deflate; 1679// or 1680// QEnableCompression:type:zlib-deflate;minsize:512; 1681// 1682// The debug stub should reply with an uncompressed "OK" packet to indicate that the 1683// request was accepted. All further packets the stub sends will use this compression. 1684// 1685// Packets are compressed as the last step before they are sent from the stub, and 1686// decompressed as the first step after they are received. The packet format in compressed 1687// mode becomes one of two: 1688// 1689// $N<uncompressed payload>#00 1690// 1691// $C<size of uncompressed payload in base10>:<compressed payload>#00 1692// 1693// Where "#00" is the actual checksum value if noack mode is not enabled. The checksum 1694// value is for the "N<uncompressed payload>" or 1695// "C<size of uncompressed payload in base10>:<compressed payload>" bytes in the packet. 1696// 1697// The size of the uncompressed payload in base10 is provided because it will simplify 1698// decompression if the final buffer size needed is known ahead of time. 1699// 1700// Compression on low-latency connections is unlikely to be an improvement. Particularly 1701// when the debug stub and lldb are running on the same host. It should only be used 1702// for slow connections, and likely only for larger packets. 1703// 1704// Example compression algorithsm that may be used include 1705// 1706// zlib-deflate 1707// The raw DEFLATE format as described in IETF RFC 1951. With the ZLIB library, you 1708// can compress to this format with an initialization like 1709// deflateInit2 (&stream, 5, Z_DEFLATED, -15, 8, Z_DEFAULT_STRATEGY) 1710// and you can decompress with an initialization like 1711// inflateInit2 (&stream, -15) 1712// 1713// lz4 1714// https://en.wikipedia.org/wiki/LZ4_(compression_algorithm) 1715// https://github.com/Cyan4973/lz4 1716// The libcompression APIs on darwin systems call this COMPRESSION_LZ4_RAW. 1717// 1718// lzfse 1719// An Apple proprietary compression algorithm implemented in libcompression. 1720// 1721// lzma 1722// libcompression implements "LZMA level 6", the default compression for the 1723// open source LZMA implementation. 1724//---------------------------------------------------------------------- 1725 1726//---------------------------------------------------------------------- 1727// "jGetLoadedDynamicLibrariesInfos" 1728// 1729// BRIEF 1730// This packet asks the remote debug stub to send the details about libraries 1731// being added/removed from the process as a performance optimization. 1732// 1733// There are three ways this packet can be used. All three return a dictionary of 1734// binary images formatted the same way. 1735// 1736// On OS X 10.11, iOS 9, tvOS 9, watchOS 2 and earlier, the packet is used like 1737// jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128} 1738// where the image_list_address is an array of {void* load_addr, void* mod_date, void* pathname} 1739// in the inferior process memory (and image_count is the number of elements in this array). 1740// lldb is using information from the dyld_all_image_infos structure to make these requests to 1741// debugserver. This use is not supported on macOS 10.12, iOS 10, tvOS 10, watchOS 3 or newer. 1742// 1743// On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer, there are two calls. One requests information 1744// on all shared libraries: 1745// jGetLoadedDynamicLibrariesInfos:{"fetch_all_solibs":true} 1746// And the second requests information about a list of shared libraries, given their load addresses: 1747// jGetLoadedDynamicLibrariesInfos:{"solib_addresses":[8382824135,3258302053,830202858503]} 1748// 1749// The second call is both a performance optimization (instead of having lldb read the mach-o header/load commands 1750// out of memory with generic read packets) but also adds additional information in the form of the 1751// filename of the shared libraries (which is not available in the mach-o header/load commands.) 1752// 1753// An example using the OS X 10.11 style call: 1754// 1755// LLDB SENDS: jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128} 1756// STUB REPLIES: ${"images":[{"load_address":4294967296,"mod_date":0,"pathname":"/tmp/a.out","uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF","mach_header":{"magic":4277009103,"cputype":16777223,"cpusubtype":18446744071562067971,"filetype":2},"segments":{"name":"__PAGEZERO","vmaddr":0,"vmsize":4294967296,"fileoff":0,"filesize":0,"maxprot":0},{"name":"__TEXT","vmaddr":4294967296,"vmsize":4096,"fileoff":0,"filesize":4096,"maxprot":7},{"name":"__LINKEDIT","vmaddr":4294971392,"vmsize":4096,"fileoff":4096,"filesize":152,"maxprot":7}}]}#00 1757// 1758// Or pretty-printed, 1759// 1760// STUB REPLIES: ${"images": 1761// [ 1762// {"load_address":4294967296, 1763// "mod_date":0, 1764// "pathname":"/tmp/a.out", 1765// "uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF", 1766// "mach_header": 1767// {"magic":4277009103, 1768// "cputype":16777223, 1769// "cpusubtype":18446744071562067971, 1770// "filetype":2 1771// }, 1772// "segments": 1773// [ 1774// {"name":"__PAGEZERO", 1775// "vmaddr":0, 1776// "vmsize":4294967296, 1777// "fileoff":0, 1778// "filesize":0, 1779// "maxprot":0 1780// }, 1781// {"name":"__TEXT", 1782// "vmaddr":4294967296, 1783// "vmsize":4096, 1784// "fileoff":0, 1785// "filesize":4096, 1786// "maxprot":7 1787// }, 1788// {"name":"__LINKEDIT", 1789// "vmaddr":4294971392, 1790// "vmsize":4096, 1791// "fileoff":4096, 1792// "filesize":152, 1793// "maxprot":7 1794// } 1795// ] 1796// } 1797// ] 1798// } 1799// 1800// 1801// This is similar to the qXfer:libraries:read packet, and it could 1802// be argued that it should be merged into that packet. A separate 1803// packet was created primarily because lldb needs to specify the 1804// number of images to be read and the address from which the initial 1805// information is read. Also the XML DTD would need to be extended 1806// quite a bit to provide all the information that the DynamicLoaderMacOSX 1807// would need to work correctly on this platform. 1808// 1809// PRIORITY TO IMPLEMENT 1810// On OS X 10.11, iOS 9, tvOS 9, watchOS 2 and older: Low. If this packet is absent, 1811// lldb will read the Mach-O headers/load commands out of memory. 1812// On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer: High. If this packet is absent, 1813// lldb will not know anything about shared libraries in the inferior, or where the main 1814// executable loaded. 1815//---------------------------------------------------------------------- 1816 1817//---------------------------------------------------------------------- 1818// "jThreadsInfo" 1819// 1820// BRIEF 1821// Ask for the server for thread stop information of all threads. 1822// 1823// PRIORITY TO IMPLEMENT 1824// Low. This is a performance optimization, which speeds up debugging by avoiding 1825// multiple round-trips for retrieving thread information. The information from this 1826// packet can be retrieved using a combination of qThreadStopInfo and m packets. 1827//---------------------------------------------------------------------- 1828 1829The data in this packet is very similar to the stop reply packets, but is packaged in 1830JSON and uses JSON arrays where applicable. The JSON output looks like: 1831 [ 1832 { "tid":1580681, 1833 "metype":6, 1834 "medata":[2,0], 1835 "reason":"exception", 1836 "qaddr":140735118423168, 1837 "registers": { 1838 "0":"8000000000000000", 1839 "1":"0000000000000000", 1840 "2":"20fabf5fff7f0000", 1841 "3":"e8f8bf5fff7f0000", 1842 "4":"0100000000000000", 1843 "5":"d8f8bf5fff7f0000", 1844 "6":"b0f8bf5fff7f0000", 1845 "7":"20f4bf5fff7f0000", 1846 "8":"8000000000000000", 1847 "9":"61a8db78a61500db", 1848 "10":"3200000000000000", 1849 "11":"4602000000000000", 1850 "12":"0000000000000000", 1851 "13":"0000000000000000", 1852 "14":"0000000000000000", 1853 "15":"0000000000000000", 1854 "16":"960b000001000000", 1855 "17":"0202000000000000", 1856 "18":"2b00000000000000", 1857 "19":"0000000000000000", 1858 "20":"0000000000000000" 1859 }, 1860 "memory":[ 1861 {"address":140734799804592,"bytes":"c8f8bf5fff7f0000c9a59e8cff7f0000"}, 1862 {"address":140734799804616,"bytes":"00000000000000000100000000000000"} 1863 ] 1864 } 1865 ] 1866 1867It contains an array of dictionaries with all of the key value pairs that are 1868normally in the stop reply packet, including the expedited registers. The registers are 1869passed as hex-encoded JSON string in debuggee-endian byte order. Note that the register 1870numbers are decimal numbers, unlike the stop-reply packet, where they are written in 1871hex. The packet also contains expedited memory in the "memory" key. This allows the 1872server to expedite memory that the client is likely to use (e.g., areas around the 1873stack pointer, which are needed for computing backtraces) and it reduces the packet 1874count. 1875 1876On macOS with debugserver, we expedite the frame pointer backchain for a thread 1877(up to 256 entries) by reading 2 pointers worth of bytes at the frame pointer (for 1878the previous FP and PC), and follow the backchain. Most backtraces on macOS and 1879iOS now don't require us to read any memory! 1880 1881//---------------------------------------------------------------------- 1882// "jGetSharedCacheInfo" 1883// 1884// BRIEF 1885// This packet asks the remote debug stub to send the details about the inferior's 1886// shared cache. The shared cache is a collection of common libraries/frameworks that 1887// are mapped into every process at the same address on Darwin systems, and can be 1888// identified by a load address and UUID. 1889// 1890// 1891// LLDB SENDS: jGetSharedCacheInfo:{} 1892// STUB REPLIES: ${"shared_cache_base_address":140735683125248,"shared_cache_uuid":"DDB8D70C-C9A2-3561-B2C8-BE48A4F33F96","no_shared_cache":false,"shared_cache_private_cache":false]}#00 1893// 1894// PRIORITY TO IMPLEMENT 1895// Low. When both lldb and the inferior process are running on the same computer, and lldb 1896// and the inferior process have the same shared cache, lldb may (as an optimization) read 1897// the shared cache out of its own memory instead of using gdb-remote read packets to read 1898// them from the inferior process. 1899//---------------------------------------------------------------------- 1900 1901//---------------------------------------------------------------------- 1902// "qQueryGDBServer" 1903// 1904// BRIEF 1905// Ask the platform for the list of gdbservers we have to connect 1906// 1907// PRIORITY TO IMPLEMENT 1908// Low. The packet is required to support connecting to gdbserver started 1909// by the platform instance automatically. 1910//---------------------------------------------------------------------- 1911 1912If the remote platform automatically started one or more gdbserver instance (without 1913lldb asking it) then it have to return the list of port number or socket name for 1914each of them what can be used by lldb to connect to those instances. 1915 1916The data in this packet is a JSON array of JSON objects with the following keys: 1917"port": <the port number to connect> (optional) 1918"socket_name": <the name of the socket to connect> (optional) 1919 1920Example packet: 1921[ 1922 { "port": 1234 }, 1923 { "port": 5432 }, 1924 { "socket_name": "foo" } 1925] 1926