This repository has been archived by the owner on Apr 23, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 227
/
lldb-gdb-remote.txt
1918 lines (1737 loc) · 87.6 KB
/
lldb-gdb-remote.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
LLDB has added new GDB server packets to better support multi-threaded and
remote debugging. Why? Normally you need to start the correct GDB and the
correct GDB server when debugging. If you have mismatch, then things go wrong
very quickly. LLDB makes extensive use of the GDB remote protocol and we
wanted to make sure that the experience was a bit more dynamic where we can
discover information about a remote target with having to know anything up
front. We also ran into performance issues with the existing GDB remote
protocol that can be overcome when using a reliable communications layer.
Some packets improve performance, others allow for remote process launching
(if you have an OS), and others allow us to dynamically figure out what
registers a thread might have. Again with GDB, both sides pre-agree on how the
registers will look (how many, their register number,name and offsets). We
prefer to be able to dynamically determine what kind of architecture, OS and
vendor we are debugging, as well as how things are laid out when it comes to
the thread register contexts. Below are the details on the new packets we have
added above and beyond the standard GDB remote protocol packets.
//----------------------------------------------------------------------
// "QStartNoAckMode"
//
// BRIEF
// Try to enable no ACK mode to skip sending ACKs and NACKs.
//
// PRIORITY TO IMPLEMENT
// High. Any GDB remote server that can implement this should if the
// connection is reliable. This improves packet throughput and increases
// the performance of the connection.
//----------------------------------------------------------------------
Having to send an ACK/NACK after every packet slows things down a bit, so we
have a way to disable ACK packets to minimize the traffic for reliable
communication interfaces (like sockets). Below GDB or LLDB will send this
packet to try and disable ACKs. All lines that start with "send packet: " are
from GDB/LLDB, and all lines that start with "read packet: " are from the GDB
remote server:
send packet: $QStartNoAckMode#b0
read packet: +
read packet: $OK#9a
send packet: +
//----------------------------------------------------------------------
// "A" - launch args packet
//
// BRIEF
// Launch a program using the supplied arguments
//
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to launch a target after
// making a connection to a GDB server that isn't already connected to
// an inferior process.
//----------------------------------------------------------------------
We have added support for the "set program arguments" packet where we can
start a connection to a remote server and then later supply the path to the
executable and the arguments to use when executing:
GDB remote docs for this:
set program arguments(reserved) Aarglen,argnum,arg,...
Where A is followed by the length in bytes of the hex encoded argument,
followed by an argument integer, and followed by the ASCII characters
converted into hex bytes foreach arg
send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00
read packet: $OK#00
The above packet helps when you have remote debugging abilities where you
could launch a process on a remote host, this isn't needed for bare board
debugging.
//----------------------------------------------------------------------
// "QEnvironment:NAME=VALUE"
//
// BRIEF
// Setup the environment up for a new child process that will soon be
// launched using the "A" packet.
//
// NB: key/value pairs are sent as-is so gdb-remote protocol meta characters
// (e.g. '#' or '$') are not acceptable. If any non-printable or
// metacharacters are present in the strings, QEnvironmentHexEncoded
// should be used instead if it is available. If you don't want to
// scan the environment strings before sending, prefer
// the QEnvironmentHexEncoded packet over QEnvironment, if it is
// available.
//
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to launch a target after
// making a connection to a GDB server that isn't already connected to
// an inferior process.
//----------------------------------------------------------------------
Both GDB and LLDB support passing down environment variables. Is it ok to
respond with a "$#00" (unimplemented):
send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00
read packet: $OK#00
This packet can be sent one or more times _prior_ to sending a "A" packet.
//----------------------------------------------------------------------
// "QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)"
//
// BRIEF
// Setup the environment up for a new child process that will soon be
// launched using the "A" packet.
//
// The only difference between this packet and QEnvironment is that the
// environment key-value pair is ascii hex encoded for transmission.
// This allows values with gdb-remote metacharacters like '#' to be sent.
//
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to launch a target after
// making a connection to a GDB server that isn't already connected to
// an inferior process.
//----------------------------------------------------------------------
Both GDB and LLDB support passing down environment variables. Is it ok to
respond with a "$#00" (unimplemented):
send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00
read packet: $OK#00
This packet can be sent one or more times _prior_ to sending a "A" packet.
//----------------------------------------------------------------------
// "QEnableErrorStrings"
//
// BRIEF
// This packet enables reporting of Error strings in remote packet
// replies from the server to client. If the server supports this
// feature, it should send an OK response. The client can expect the
// following error replies if this feature is enabled in the server ->
//
// EXX;AAAAAAAAA
//
// where AAAAAAAAA will be a hex encoded ASCII string.
// XX is hex encoded byte number.
//
// It must be noted that even if the client has enabled reporting
// strings in error replies, it must not expect error strings to all
// error replies.
//
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to provide strings that
// are human readable along with an error code.
//----------------------------------------------------------------------
send packet: $QEnableErrorStrings
read packet: $OK#00
//----------------------------------------------------------------------
// "QSetSTDIN:<ascii-hex-path>"
// "QSetSTDOUT:<ascii-hex-path>"
// "QSetSTDERR:<ascii-hex-path>"
//
// BRIEF
// Setup where STDIN, STDOUT, and STDERR go prior to sending an "A"
// packet.
//
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to launch a target after
// making a connection to a GDB server that isn't already connected to
// an inferior process.
//----------------------------------------------------------------------
When launching a program through the GDB remote protocol with the "A" packet,
you might also want to specify where stdin/out/err go:
QSetSTDIN:<ascii-hex-path>
QSetSTDOUT:<ascii-hex-path>
QSetSTDERR:<ascii-hex-path>
These packets must be sent _prior_ to sending a "A" packet.
//----------------------------------------------------------------------
// "QSetWorkingDir:<ascii-hex-path>"
//
// BRIEF
// Set the working directory prior to sending an "A" packet.
//
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to launch a target after
// making a connection to a GDB server that isn't already connected to
// an inferior process.
//----------------------------------------------------------------------
Or specify the working directory:
QSetWorkingDir:<ascii-hex-path>
This packet must be sent _prior_ to sending a "A" packet.
//----------------------------------------------------------------------
// "QSetDisableASLR:<bool>"
//
// BRIEF
// Enable or disable ASLR on the next "A" packet.
//
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to launch a target after
// making a connection to a GDB server that isn't already connected to
// an inferior process and if the target supports disabling ASLR
// (Address space layout randomization).
//----------------------------------------------------------------------
Or control if ASLR is enabled/disabled:
send packet: QSetDisableASLR:1
read packet: OK
send packet: QSetDisableASLR:0
read packet: OK
This packet must be sent _prior_ to sending a "A" packet.
//----------------------------------------------------------------------
// QListThreadsInStopReply
//
// BRIEF
// Enable the threads: and thread-pcs: data in the question-mark packet
// ("T packet") responses when the stub reports that a program has
// stopped executing.
//
// PRIORITY TO IMPLEMENT
// Performance. This is a performance benefit to lldb if the thread id's
// and thread pc values are provided to lldb in the T stop packet -- if
// they are not provided to lldb, lldb will likely need to send one to
// two packets per thread to fetch the data at every private stop.
//----------------------------------------------------------------------
send packet: QListThreadsInStopReply
read packet: OK
//----------------------------------------------------------------------
// jTraceStart:
//
// BRIEF
// Packet for starting trace of type lldb::TraceType. The following
// parameters should be appended to the packet formatted as a JSON
// dictionary, where the schematic for the JSON dictionary in terms of
// the recognized Keys is given below in the table.
// Different tracing types could require different custom parameters.
// Such custom tracing parameters if needed should be collectively
// specified in a JSON dictionary and the dictionary can be appended
// to this packet (as Value corresponding to "params"). Since sending
// JSON data over gdb-remote protocol has certain limitations, binary
// escaping convention should be used.
//
// Following is the list of parameters -
//
// Key Value (Integer) (O)Optional/
// (except params which should be a (M)Mandatory
// JSON dictionary)
// ========== ====================================================
//
// type The type of trace to start (see M
// lldb-enumerations for TraceType)
//
// buffersize The size of the buffer to allocate M
// for trace gathering.
//
// threadid The id of the thread to start tracing O
// on.
//
// metabuffersize The size of buffer to hold meta data O
// used for decoding the trace data.
//
// params Any parameters that are specific to O
// certain trace technologies should be
// collectively specified as a JSON
// dictionary
// ========== ====================================================
//
// Each tracing instance is identified by a trace id which is returned
// as the reply to this packet. In case the tracing failed to begin an
// error code along with a hex encoded ASCII message is returned
// instead.
//----------------------------------------------------------------------
send packet: jTraceStart:{"type":<type>,"buffersize":<buffersize>}]
read packet: <trace id>/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
// jTraceStop:
//
// BRIEF
// Stop tracing instance with trace id <trace id>, of course trace
// needs to be started before. The following parameters should be
// formatted as a JSON dictionary to the packet. Since sending
// JSON data over gdb-remote protocol has certain limitations, binary
// escaping convention should be used.
//
// Following is the list of parameters -
//
// Key Value (Integer) (O)Optional/
// (M)Mandatory
// ========== ====================================================
//
// traceid The trace id of the tracing instance M
//
// threadid The id of the thread to stop tracing O
// on. Since <trace id> could map to
// multiple trace instances (in case it
// maps to the complete process), the
// threadid of a particular thread could
// be appended as "threadid:<thread id>;"
// to stop tracing on that thread.
// ========== ====================================================
//
// An OK response is sent in case of success else an error code along
// with a hex encoded ASCII message is returned.
//----------------------------------------------------------------------
send packet: jTraceStop:{"traceid":<trace id>}]
read packet: <OK response>/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
// jTraceBufferRead:
//
// BRIEF
// Packet for reading the trace for tracing instance <trace id>, i.e the
// id obtained from StartTrace API. The following parameters should be
// formatted as a JSON dictionary to the packet. Since sending
// JSON data over gdb-remote protocol has certain limitations, binary
// escaping convention should be used.
//
// Following is the list of parameters -
//
// Key Value (Integer) (O)Optional/
// (M)Mandatory
// ========== ====================================================
// traceid The trace id of the tracing instance M
//
// offset The offset to start reading the data M
// from.
//
// buffersize The size of the data intended to read. M
//
// threadid The id of the thread to retrieve data O
// from.
// ========== ====================================================
//
// The trace data is sent as raw binary data if the read was successful
// else an error code along with a hex encoded ASCII message is sent.
//----------------------------------------------------------------------
send packet: jTraceBufferRead:{"traceid":<trace id>,"offset":<byteoffset>,"buffersize":<byte_count>}]
read packet: <binary trace data>/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
// jTraceMetaRead:
//
// BRIEF
// Similar Packet as above except it reads meta data.
//----------------------------------------------------------------------
/----------------------------------------------------------------------
// jTraceConfigRead:
//
// BRIEF
// Request the trace configuration for the tracing instance with id
// <trace id>.
//
// Following is the list of parameters -
//
// Key Value (Integer) (O)Optional/
// (M)Mandatory
// ========== ====================================================
// traceid The trace id of the tracing instance M
//
// threadid The id of the thread to obtain trace O
// configuration from. Since <trace id>
// could map to multiple trace instances
// (in case it maps to the complete
// process), the threadid of a particular
// thread could be appended as
// "threadid:<thread id>;" to obtain the
// trace configuration of that thread.
// ========== ====================================================
//
// In the response packet the trace configuration is sent as text,
// formatted as a JSON dictionary. Since sending JSON data over
// gdb-remote protocol has certain limitations, binary escaping
// convention is used.
// In case the trace instance with the <trace id> was not found, an
// error code along with a hex encoded ASCII message is returned.
//----------------------------------------------------------------------
send packet: jTraceConfigRead:{"traceid":<trace id>}
read packet: {"conf1":<conf1>,"conf2":<conf2>,"params":{"paramName":paramValue}]}];/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
// "qRegisterInfo<hex-reg-id>"
//
// BRIEF
// Discover register information from the remote GDB server.
//
// PRIORITY TO IMPLEMENT
// High. Any target that can self describe its registers, should do so.
// This means if new registers are ever added to a remote target, they
// will get picked up automatically, and allows registers to change
// depending on the actual CPU type that is used.
//
// NB: As of summer 2015, lldb can get register information from the
// "qXfer:features:read:target.xml" FSF gdb standard register packet
// where the stub provides register definitions in an XML file.
// If qXfer:features:read:target.xml is supported, qRegisterInfo does
// not need to be implemented.
//----------------------------------------------------------------------
With LLDB, for register information, remote GDB servers can add
support for the "qRegisterInfoN" packet where "N" is a zero based
base16 register number that must start at zero and increase by one
for each register that is supported. The response is done in typical
GDB remote fashion where a series of "KEY:VALUE;" pairs are returned.
An example for the x86_64 registers is included below:
send packet: $qRegisterInfo0#00
read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00
send packet: $qRegisterInfo1#00
read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00
send packet: $qRegisterInfo2#00
read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00
send packet: $qRegisterInfo3#00
read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00
send packet: $qRegisterInfo4#00
read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00
send packet: $qRegisterInfo5#00
read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00
send packet: $qRegisterInfo6#00
read 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
send packet: $qRegisterInfo7#00
read 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
send packet: $qRegisterInfo8#00
read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00
send packet: $qRegisterInfo9#00
read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00
send packet: $qRegisterInfoa#00
read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00
send packet: $qRegisterInfob#00
read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00
send packet: $qRegisterInfoc#00
read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00
send packet: $qRegisterInfod#00
read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00
send packet: $qRegisterInfoe#00
read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00
send packet: $qRegisterInfof#00
read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00
send packet: $qRegisterInfo10#00
read 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
send packet: $qRegisterInfo11#00
read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00
send packet: $qRegisterInfo12#00
read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00
send packet: $qRegisterInfo13#00
read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00
send packet: $qRegisterInfo14#00
read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00
send packet: $qRegisterInfo15#00
read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo16#00
read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo17#00
read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo18#00
read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo19#00
read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo1a#00
read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo1b#00
read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo1c#00
read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo1d#00
read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo1e#00
read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00
send packet: $qRegisterInfo1f#00
read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00
send packet: $qRegisterInfo20#00
read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00
send packet: $qRegisterInfo21#00
read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00
send packet: $qRegisterInfo22#00
read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00
send packet: $qRegisterInfo23#00
read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00
send packet: $qRegisterInfo24#00
read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00
send packet: $qRegisterInfo25#00
read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00
send packet: $qRegisterInfo26#00
read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00
send packet: $qRegisterInfo27#00
read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00
send packet: $qRegisterInfo28#00
read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00
send packet: $qRegisterInfo29#00
read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00
send packet: $qRegisterInfo2a#00
read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00
send packet: $qRegisterInfo2b#00
read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00
send packet: $qRegisterInfo2c#00
read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00
send packet: $qRegisterInfo2d#00
read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00
send packet: $qRegisterInfo2e#00
read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00
send packet: $qRegisterInfo2f#00
read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00
send packet: $qRegisterInfo30#00
read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00
send packet: $qRegisterInfo31#00
read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00
send packet: $qRegisterInfo32#00
read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00
send packet: $qRegisterInfo33#00
read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00
send packet: $qRegisterInfo34#00
read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00
send packet: $qRegisterInfo35#00
read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00
send packet: $qRegisterInfo36#00
read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00
send packet: $qRegisterInfo37#00
read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00
send packet: $qRegisterInfo38#00
read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00
send packet: $qRegisterInfo39#00
read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00
send packet: $qRegisterInfo3a#00
read packet: $E45#00
As we see above we keep making subsequent calls to the remote server to
discover all registers by increasing the number appended to qRegisterInfo and
we get a response back that is a series of "key=value;" strings.
The offset: fields should not leave a gap anywhere in the g/G packet -- the
register values should be appended one after another. For instance, if the
register context for a thread looks like
struct rctx {
uint32_t gpr1; // offset 0
uint32_t gpr2; // offset 4
uint32_t gpr3; // offset 8
uint64_t fp1; // offset 16
};
You may end up with a 4-byte gap between gpr3 and fp1 on architectures
that align values like this. The correct offset: value for fp1 is 12 -
in the g/G packet fp1 will immediately follow gpr3, even though the
in-memory thread structure has an empty 4 bytes for alignment between
these two registers.
The keys and values are detailed below:
Key Value
========== ================================================================
name The primary register name as a string ("rbp" for example)
alt-name An alternate name for a register as a string ("fp" for example for
the above "rbp")
bitsize Size in bits of a register (32, 64, etc). Base 10.
offset The offset within the "g" and "G" packet of the register data for
this register. This is the byte offset once the data has been
transformed into binary, not the character offset into the g/G
packet. Base 10.
encoding The encoding type of the register which must be one of:
uint (unsigned integer)
sint (signed integer)
ieee754 (IEEE 754 float)
vector (vector register)
format The preferred format for display of this register. The value must
be one of:
binary
decimal
hex
float
vector-sint8
vector-uint8
vector-sint16
vector-uint16
vector-sint32
vector-uint32
vector-float32
vector-uint128
set The register set name as a string that this register belongs to.
gcc The GCC compiler registers number for this register (used for
EH frame and other compiler information that is encoded in the
executable files). The supplied number will be decoded like a
string passed to strtoul() with a base of zero, so the number
can be decimal, or hex if it is prefixed with "0x".
NOTE: If the compiler doesn't have a register number for this
register, this key/value pair should be omitted.
dwarf The DWARF register number for this register that is used for this
register in the debug information. The supplied number will be decoded
like a string passed to strtoul() with a base of zero, so the number
can be decimal, or hex if it is prefixed with "0x".
NOTE: If the compiler doesn't have a register number for this
register, this key/value pair should be omitted.
generic If the register is a generic register that most CPUs have, classify
it correctly so the debugger knows. Valid values are one of:
pc (a program counter register. for example "name=eip;" (i386),
"name=rip;" (x86_64), "name=r15;" (32 bit arm) would
include a "generic=pc;" key value pair)
sp (a stack pointer register. for example "name=esp;" (i386),
"name=rsp;" (x86_64), "name=r13;" (32 bit arm) would
include a "generic=sp;" key value pair)
fp (a frame pointer register. for example "name=ebp;" (i386),
"name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx
ABI) would include a "generic=fp;" key value pair)
ra (a return address register. for example "name=lr;" (32 bit ARM)
would include a "generic=ra;" key value pair)
fp (a CPU flags register. for example "name=eflags;" (i386),
"name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM)
would include a "generic=flags;" key value pair)
arg1 - arg8 (specified for registers that contain function
arguments when the argument fits into a register)
container-regs
The value for this key is a comma separated list of raw hex (optional
leading "0x") register numbers.
This specifies that this register is contained in other concrete
register values. For example "eax" is in the lower 32 bits of the
"rax" register value for x86_64, so "eax" could specify that it is
contained in "rax" by specifying the register number for "rax" (whose
register number is 0x00)
"container-regs:00;"
If a register is comprised of one or more registers, like "d0" is ARM
which is a 64 bit register, it might be made up of "s0" and "s1". If
the register number for "s0" is 0x20, and the register number of "s1"
is "0x21", the "container-regs" key/value pair would be:
"container-regs:20,21;"
This is handy for defining what GDB used to call "pseudo" registers.
These registers are never requested by LLDB via the register read
or write packets, the container registers will be requested on behalf
of this register.
invalidate-regs
The value for this key is a comma separated list of raw hex (optional
leading "0x") register numbers.
This specifies which register values should be invalidated when this
register is modified. For example if modifying "eax" would cause "rax",
"eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15,
ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value
pair would be:
"invalidate-regs:0,15,25,35,39;"
If there is a single register that gets invalidated, then omit the comma
and just list a single register:
"invalidate-regs:0;"
This is handy when modifying a specific register can cause other
register values to change. For example, when debugging an ARM target,
modifying the CPSR register can cause the r8 - r14 and cpsr value to
change depending on if the mode has changed.
//----------------------------------------------------------------------
// "qPlatform_shell"
//
// BRIEF
// Run a command in a shell on the connected remote machine.
//
// PRIORITY TO IMPLEMENT
// High. This command allows LLDB clients to run arbitrary shell
// commands on a remote host.
//
/----------------------------------------------------------------------
The request consists of the command to be executed encoded in ASCII characters
converted into hex bytes.
The response to this packet consists of the letter F followed by the return code,
followed by the signal number (or 0 if no signal was delivered), and escaped bytes
of captured program output.
Below is an example communication from a client sending an "ls -la" command:
send packet: $qPlatform_shell:6c73202d6c61,00000002#ec
read packet: $F,00000000,00000000,total 4736
drwxrwxr-x 16 username groupname 4096 Aug 15 21:36 .
drwxr-xr-x 17 username groupname 4096 Aug 10 16:39 ..
-rw-rw-r-- 1 username groupname 73875 Aug 12 16:46 notes.txt
drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
-rw-r--r-- 1 username groupname 2792 Aug 12 16:46 a.out
-rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile
//----------------------------------------------------------------------
// "qPlatform_mkdir"
//
// BRIEF
// Creates a new directory on the connected remote machine.
//
// PRIORITY TO IMPLEMENT
// Low. This command allows LLDB clients to create new directories on
// a remote host.
//
/----------------------------------------------------------------------
Request:
qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>
Reply:
F<mkdir-return-code>
mkdir called successfully and returned with the given return code
Exx
An error occurred
//----------------------------------------------------------------------
// "qPlatform_chmod"
//
// BRIEF
// Change the permissions of a file on the connected remote machine.
//
// PRIORITY TO IMPLEMENT
// Low. This command allows LLDB clients to change the permissions of
// a file on the remote host.
//
/----------------------------------------------------------------------
Request:
qPlatform_chmod:<hex-file-mode>,<ascii-hex-path>
Reply:
F<chmod-return-code>
chmod called successfully and returned with the given return code
Exx
An error occurred
//----------------------------------------------------------------------
// "qHostInfo"
//
// BRIEF
// Get information about the host we are remotely connected to.
//
// PRIORITY TO IMPLEMENT
// High. This packet is usually very easy to implement and can help
// LLDB select the correct plug-ins for the job based on the target
// triple information that is supplied.
//----------------------------------------------------------------------
LLDB supports a host info call that gets all sorts of details of the system
that is being debugged:
send packet: $qHostInfo#00
read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00
Key value pairs are one of:
cputype: is a number that is the mach-o CPU type that is being debugged (base 10)
cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged (base 10)
triple: a string for the target triple (x86_64-apple-macosx) that can be used to specify arch + vendor + os in one entry
vendor: a string for the vendor (apple), not needed if "triple" is specified
ostype: a string for the OS being debugged (macosx, linux, freebsd, ios, watchos), not needed if "triple" is specified
endian: is one of "little", "big", or "pdp"
ptrsize: an unsigned number that represents how big pointers are in bytes on the debug target
hostname: the hostname of the host that is running the GDB server if available
os_build: a string for the OS build for the remote host as a string value
os_kernel: a string describing the kernel version
os_version: a version string that represents the current OS version (10.8.2)
watchpoint_exceptions_received: one of "before" or "after" to specify if a watchpoint is triggered before or after the pc when it stops
default_packet_timeout: an unsigned number that specifies the default timeout in seconds
distribution_id: optional. For linux, specifies distribution id (e.g. ubuntu, fedora, etc.)
osmajor: optional, specifies the major version number of the OS (e.g. for macOS 10.12.2, it would be 10)
osminor: optional, specifies the minor version number of the OS (e.g. for macOS 10.12.2, it would be 12)
ospatch: optional, specifies the patch level number of the OS (e.g. for macOS 10.12.2, it would be 2)
//----------------------------------------------------------------------
// "qGDBServerVersion"
//
// BRIEF
// Get version information about this implementation of the gdb-remote
// protocol.
//
// PRIORITY TO IMPLEMENT
// High. This packet is usually very easy to implement and can help
// LLDB to work around bugs in a server's implementation when they
// are found.
//----------------------------------------------------------------------
The goal of this packet is to provide enough information about an
implementation of the gdb-remote-protocol server that lldb can
work around implementation problems that are discovered after the
version has been released/deployed. The name and version number
should be sufficiently unique that lldb can unambiguously identify
the origin of the program (for instance, debugserver from lldb) and
the version/submission number/patch level of the program - whatever
is appropriate for your server implementation.
The packet follows the key-value pair model, semicolon separated.
send packet: $qGDBServerVersion#00
read packet: $name:debugserver;version:310.2;#00
Other clients may find other key-value pairs to be useful for identifying
a gdb stub. Patch level, release name, build number may all be keys that
better describe your implementation's version.
Suggested key names:
name : the name of your remote server - "debugserver" is the lldb standard
implementation
version : identifies the version number of this server
patch_level : the patch level of this server
release_name : the name of this release, if your project uses names
build_number : if you use a build system with increasing build numbers,
this may be the right key name for your server
major_version : major version number
minor_version : minor version number
//----------------------------------------------------------------------
// "qProcessInfo"
//
// BRIEF
// Get information about the process we are currently debugging.
//
// PRIORITY TO IMPLEMENT
// Medium. On systems which can launch multiple different architecture processes,
// the qHostInfo may not disambiguate sufficiently to know what kind of
// process is being debugged.
// e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible,
// and with Mach-O universal files, the executable file may contain both 32- and
// 64-bit slices so it may be impossible to know until you're attached to a real
// process to know what you're working with.
//
// All numeric fields return base-16 numbers without any "0x" prefix.
//----------------------------------------------------------------------
An i386 process:
send packet: $qProcessInfo#00
read 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
An x86_64 process:
send packet: $qProcessInfo#00
read 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
Key value pairs include:
pid: the process id
parent-pid: the process of the parent process (often debugserver will become the parent when attaching)
real-uid: the real user id of the process
real-gid: the real group id of the process
effective-uid: the effective user id of the process
effective-gid: the effective group id of the process
cputype: the Mach-O CPU type of the process (base 16)
cpusubtype: the Mach-O CPU subtype of the process (base 16)
ostype: is a string the represents the OS being debugged (darwin, linux, freebsd)
vendor: is a string that represents the vendor (apple)
endian: is one of "little", "big", or "pdp"
ptrsize: is a number that represents how big pointers are in bytes
//----------------------------------------------------------------------
// "qShlibInfoAddr"
//
// BRIEF
// Get an address where the dynamic linker stores information about
// where shared libraries are loaded.
//
// PRIORITY TO IMPLEMENT
// High if you have a dynamic loader plug-in in LLDB for your target
// triple (see the "qHostInfo" packet) that can use this information.
// Many times address load randomization can make it hard to detect
// where the dynamic loader binary and data structures are located and
// some platforms know, or can find out where this information is.
//
// Low if you have a debug target where all object and symbol files
// contain static load addresses.
//----------------------------------------------------------------------
LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each
debugger as to where to find the dynamic loader information. For darwin
binaries that run in user land this is the address of the "all_image_infos"
structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO
call. The result is returned as big endian hex bytes that are the address
value:
send packet: $qShlibInfoAddr#00
read packet: $7fff5fc40040#00
//----------------------------------------------------------------------
// "qThreadStopInfo<tid>"
//
// BRIEF
// Get information about why a thread, whose ID is "<tid>", is stopped.
//
// PRIORITY TO IMPLEMENT
// High if you need to support multi-threaded or multi-core debugging.
// Many times one thread will hit a breakpoint and while the debugger
// is in the process of suspending the other threads, other threads
// will also hit a breakpoint. This packet allows LLDB to know why all
// threads (live system debug) / cores (JTAG) in your program have
// stopped and allows LLDB to display and control your program
// correctly.
//----------------------------------------------------------------------
LLDB tries to use the "qThreadStopInfo" packet which is formatted as
"qThreadStopInfo%x" where %x is the hex thread ID. This requests information
about why a thread is stopped. The response is the same as the stop reply
packets and tells us what happened to the other threads. The standard GDB
remote packets love to think that there is only _one_ reason that _one_ thread
stops at a time. This allows us to see why all threads stopped and allows us
to implement better multi-threaded debugging support.
//----------------------------------------------------------------------
// "QThreadSuffixSupported"
//
// BRIEF
// Try to enable thread suffix support for the 'g', 'G', 'p', and 'P'
// packets.
//
// PRIORITY TO IMPLEMENT
// High. Adding a thread suffix allows us to read and write registers
// more efficiently and stops us from having to select a thread with
// one packet and then read registers with a second packet. It also
// makes sure that no errors can occur where the debugger thinks it
// already has a thread selected (see the "Hg" packet from the standard
// GDB remote protocol documentation) yet the remote GDB server actually
// has another thread selected.
//----------------------------------------------------------------------
When reading thread registers, you currently need to set the current
thread, then read the registers. This is kind of cumbersome, so we added the
ability to query if the remote GDB server supports adding a "thread:<tid>;"
suffix to all packets that request information for a thread. To test if the
remote GDB server supports this feature:
send packet: $QThreadSuffixSupported#00
read packet: OK
If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a
thread suffix. So to send a 'g' packet (read all register values):
send packet: $g;thread:<tid>;#00
read packet: ....
send packet: $G;thread:<tid>;#00
read packet: ....
send packet: $p1a;thread:<tid>;#00
read packet: ....
send packet: $P1a=1234abcd;thread:<tid>;#00
read packet: ....
otherwise, without this you would need to always send two packets:
send packet: $Hg<tid>#00
read packet: ....
send packet: $g#00
read packet: ....
We also added support for allocating and deallocating memory. We use this to
allocate memory so we can run JITed code.
//----------------------------------------------------------------------
// "_M<size>,<permissions>"
//
// BRIEF
// Allocate memory on the remote target with the specified size and
// permissions.
//
// PRIORITY TO IMPLEMENT
// High if you want LLDB to be able to JIT code and run that code. JIT
// code also needs data which is also allocated and tracked.