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