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
|
<HTML>
<!--This file created 3:45 AM 8/23/99 by Claris Home Page version 3.0-->
<HEAD>
<TITLE>Debugger</TITLE>
<META NAME=GENERATOR CONTENT="Claris Home Page 3.0">
<X-CLARIS-WINDOW TOP=23 BOTTOM=859 LEFT=623 RIGHT=1234>
<X-CLARIS-TAGVIEW MODE=minimal>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"><META NAME="Author" CONTENT="Keith Rollin">
</HEAD>
<BODY>
<H1><CENTER>Palm Debugger Protocol</CENTER></H1>
<CENTER><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="80%">
<TR>
<TD>
<H3>Document Order</H3>
</TD>
<TD>
<H3>Alphabetical Order</H3>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Overview">Overview</A></P>
</TD>
<TD>
<P><A HREF="#Continue Command">Continue Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#State Command">State Command</A></P>
</TD>
<TD>
<P><A HREF="#Find Command">Find Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Read Memory Command">Read Memory
Command</A></P>
</TD>
<TD>
<P><A HREF="#Get Breakpoints Command">Get Breakpoints
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Write Memory Command">Write Memory
Command</A></P>
</TD>
<TD>
<P><A HREF="#Get Routine Name Command">Get Routine Name
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Single Step Command">Single Step
Command</A></P>
</TD>
<TD>
<P><A HREF="#Get Trap Breaks Command">Get Trap Breaks
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Get Routine Name Command">Get Routine Name
Command</A></P>
</TD>
<TD>
<P><A HREF="#Get Trap Conditionals Command">Get Trap
Conditionals Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Read Registers Command">Read Registers
Command</A></P>
</TD>
<TD>
<P><A HREF="#Message Command">Message Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Write Registers Command">Write Registers
Command</A></P>
</TD>
<TD>
<P><A HREF="#Overview">Overview</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Continue Command">Continue Command</A></P>
</TD>
<TD>
<P><A HREF="#Read Memory Command">Read Memory
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Get Breakpoints Command">Get Breakpoints
Command</A></P>
</TD>
<TD>
<P><A HREF="#Read Registers Command">Read Registers
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Set Breakpoints Command">Set Breakpoints
Command</A></P>
</TD>
<TD>
<P><A HREF="#RPC Command">RPC Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Toggle Debugger Breaks Command">Toggle Debugger
Breaks Command</A></P>
</TD>
<TD>
<P><A HREF="#Set Breakpoints Command">Set Breakpoints
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Get Trap Breaks Command">Get Trap Breaks
Command</A></P>
</TD>
<TD>
<P><A HREF="#Set Trap Breaks Command">Set Trap Breaks
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Set Trap Breaks Command">Set Trap Breaks
Command</A></P>
</TD>
<TD>
<P><A HREF="#Set Trap Conditionals Command">Set Trap
Conditionals Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Find Command">Find Command</A></P>
</TD>
<TD>
<P><A HREF="#Single Step Command">Single Step
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Message Command">Message Command</A></P>
</TD>
<TD>
<P><A HREF="#State Command">State Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#RPC Command">RPC Command</A></P>
</TD>
<TD>
<P><A HREF="#Toggle Debugger Breaks Command">Toggle Debugger
Breaks Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Get Trap Conditionals Command">Get Trap
Conditionals Command</A></P>
</TD>
<TD>
<P><A HREF="#Write Memory Command">Write Memory
Command</A></P>
</TD>
</TR>
<TR>
<TD>
<P><A HREF="#Set Trap Conditionals Command">Set Trap
Conditionals Command</A></P>
</TD>
<TD>
<P><A HREF="#Write Registers Command">Write Registers
Command</A></P>
</TD>
</TR>
</TABLE>
</CENTER>
<H3><A NAME=Overview></A>Overview</H3>
<P>In this document, "target" refers to the object being debugged.
This could be the Palm ROM, or Palm OS Emulator. "Host" refers
to the debugger, which could be either the Metrowerks debugger or the
Palm Debugger. The target side of the debugger communicates by
sending command packets to the user interface on the host side.
Basically, the target side acts as a slave to the host, carrying out
commands and reporting back results.</P>
<P>The target side must be able to respond to some basic command
types sent from the host side. These are: get state, display memory,
set memory, single step, get routine name, display registers, set
registers, continue, set breakpoint, clear breakpoint, set a-trap,
clear a-trap, find, and remote procedure call. All high-level
commands that a user enters from the host side are broken down into
one or more of these basic target commands, which are then sent to
the target.</P>
<P>A command packet can be a request packet, response packet, or
message packet. Request packets are sent from the host to the target
and must be answered by an appropriate response packet from the
target. Message packets are sent from either the target or the host
and merely report status information and do not require a response
from the recipient.</P>
<P>There is no extensive protocol involved between the host and
target. Basically, the host sends a request packet and waits for a
response from the target, or a timeout. If a response is not detected
by the timeout period, the host does not retry the request but could
display a message to the user saying that the target is not
responding. Usually, if the target does not respond, it means either
that the target is currently executing code and has not encountered a
breakpoint, or that the target is so messed up that it can't even run
the debugger.</P>
<P>Figure 1 shows the structure of request, response, and message
packets. <FONT FACE="Times">Basically, every packet consists of a
packet header, a variable length packet body, and a packet footer.
The maximim size of a packet body is 272 bytes. The packet header
starts with the key 24-bit value $BEEFED and includes packet header
information and a checksum of just the header itself. The packet
footer contains a 16-bit CRC of the header and body (not
footer).</FONT></P>
<P><FONT FACE="Times">Following the 24-bit value $BEEFED at the start
of the packet header is a destination socket ID byte, a source socket
ID byte, a packet type byte, a 2 byte body size, a transaction ID
byte, and an 8 bit checksum of the header. The destination and source
socket IDs and the packet type bytes are always 0 for debugger
packets. The bodySize field is the number of bytes that are in the
body - which will depend on the particular command being sent. The
transaction ID is an 8 bit value that gets incremented every time a
command is sent from the host. In order for a response packet from
the target to be recognized by the host, its transaction ID must
match the transaction ID of the original request packet.</FONT></P>
<P><FONT FACE="Times">The packet body starts with a command byte
immediately followed by a filler byte. </FONT>The command byte
encodes the particular command being sent or acknowledged. Request
packets always have the upper bit of the command byte clear, response
packets have the upper bit set. Each command has it's own specific
structure following the command and filler bytes. </P>
<P> </P>
<P><TT> +--------------------+<BR>
| $BE (1) |<BR>
| $EF (1) |<BR>
| $ED (1) |<BR>
| dest ID (1) | Header (10 bytes)<BR>
| src ID (1) |<BR>
| type (1) |<BR>
| bodySize (2) |<BR>
| transID (1) |<BR>
| checkSum (1) |<BR>
+--------------------+<BR>
| command (1) |<BR>
| filler (1) | Body (2-272 bytes)<BR>
| variable size data |<BR>
+--------------------+<BR>
| CRC (2) | Footer (2 bytes)<BR>
+--------------------+<BR>
</TT></P>
<CENTER><B>Figure 1 - Structure of Packets</B></CENTER>
<P> </P>
<H3><A NAME="State Command"></A>State Command</H3>
<P>Figure 2 shows the structure of the request and response bodies
for the state command. The host sends this command in order to
determine the current state of the target, including the current
program counter, the values of all the registers, the reason why the
target entered the debugger, the current breakpoints, and the name of
the routine that the program counter is in. The target will also send
a state response packet to the host whenever it encounters an
exception and enters the debugger - whether due to a breakpoint, bus
error, single step, etc. This is the only time a response packet is
sent to the host without a corresponding request packet from the
host.</P>
<PRE><TT>#define sysPktStateCmd 0x00
#define sysPktStateRsp 0x80</TT></PRE>
<BLOCKQUOTE><PRE><I><TT>Max length of a routine name</TT></I></PRE></BLOCKQUOTE>
<PRE><TT>#define sysPktMaxNameLen 32</TT></PRE>
<BLOCKQUOTE><PRE><I><TT>Number of remote code words to send in the 'state response' packet</TT></I></PRE></BLOCKQUOTE>
<PRE><TT>#define sysPktStateRspInstWords 15
#define dbgNormalBreakpoints 5
#define dbgTempBPIndex dbgNormalBreakpoints
#define dbgTotalBreakpoints (dbgTempBPIndex+1)
typedef struct BreakpointType
{
Ptr addr; // address of breakpoint
Boolean enabled; // true if enabled
Boolean installed; // for alignment
} BreakpointType;
typedef struct SysPktStateCmdType
{
_sysPktBodyCommon; // Common Body header
} SysPktStateCmdCmdType;</TT></PRE>
<BLOCKQUOTE><PRE><I><TT>Packet Body structure for the state command response packet</TT></I></PRE></BLOCKQUOTE>
<PRE><TT>typedef struct SysPktStateRspType
{
_sysPktBodyCommon; // Common Body header
Boolean resetted; // true if target has just reset
Word exceptionId; // exception which caused the
// debugger to be entered.
M68KregsType reg; // current remote registers.
Word inst[sysPktStateRspInstWords];
// instruction buffer for
// code beginning at PC.
BreakpointType bp[dbgTotalBreakpoints]; // current breakpoints
void* startAddr; // start address of routine
void* endAddr; // end address of routine
char name[sysPktMaxNameLen]; // routine name (0 or more chars),
// immediately follows the address range.
Byte trapTableRev; // rev of trap table. Used to determine
// when host's trap table cache is invalid
} SysPktStateRspType;</TT></PRE>
<CENTER><B>Figure 2 - State Command</B></CENTER>
<P>The resetted field is non-zero if the target has reset itself
since the last time the debugger was entered. The host can use the
exceptionID field to determine why the debugger on the target was
entered because it contains the address of the exception vector: $8
for a bus error, $7C for a non-maskable interrupt, etc. The 8 data
registers are stored in the packet body starting from D0. The 7
address registers are stored starting from A0. The instruction buffer
contains the next 30 bytes of code starting from the current program
counter. The breakpoint list contains the list of the current
breakpoints on the device. This is a fixed length list of 6
breakpoints - unused entries will have 0 in the enabled and installed
fields. The last breakpoint in the list (breakpoint #5) is used
exclusively for temporary breakpoints installed by the debugger for
implementing commands like GoTill (gt).</P>
<P>The routineStart, routineEnd, and routineName fields contain the
starting and ending address and name of the current routine. The
target side of the debugger determines this information. A routine
name is placed at the end of every routine by the compiler and the
target side of the debugger scans forward and backwards from the
current program counter to determine this information.</P>
<P> </P>
<H3><A NAME="Read Memory Command"></A>Read Memory Command</H3>
<P>Figure 3 shows the structure of the request and response bodies
for the read command. This command is sent by the host in order to
read memory on the target. It can return up to 256 bytes of data. The
size of the response body depends on the number of bytes requested in
the request packet.</P>
<PRE><TT>#define sysPktReadMemCmd 0x01
#define sysPktReadMemRsp 0x81
typedef struct SysPktReadMemCmdType
{
_sysPktBodyCommon; // Common Body header
void* address; // Address to read
Word numBytes; // # of bytes to read
} SysPktReadMemCmdType;
typedef struct SysPktReadMemRspType
{
_sysPktBodyCommon; // Common Body header
// Byte data[?]; // variable size
} SysPktReadMemRspType;</TT></PRE>
<CENTER><B>Figure 3 - Read Command</B></CENTER>
<P> </P>
<H3><A NAME="Write Memory Command"></A>Write Memory Command</H3>
<P>Figure 4 shows the structure of the request and response bodies
for the write command. This command is sent by the host in order to
write memory on the target. It can write up to 256 bytes of data. The
size of the request packet depends on the number of bytes that need
to be written.</P>
<PRE><TT>#define sysPktWriteMemCmd 0x02
#define sysPktWriteMemRsp 0x82
typedef struct SysPktWriteMemCmdType
{
_sysPktBodyCommon; // Common Body header
void* address; // Address to write
Word numBytes; // # of bytes to write
// Byte data[?]; // variable size data
} SysPktWriteMemCmdType;
typedef struct SysPktWriteMemRspType
{
_sysPktBodyCommon; // Common Body header
} SysPktWriteMemRspType;</TT></PRE>
<CENTER><B>Figure 4 - Write Command</B></CENTER>
<P> </P>
<H3><A NAME="Single Step Command"></A>Single Step Command</H3>
<P><STRIKE>Figure 5 shows the structure of the request and response
bodies for the singleStep command. This command is sent by the host
to tell the target to execute the next instruction. This command and
the continue command (see below) are unique in that they do not get a
respective response back from the target. The host relies on the fact
that when the target re-enters the debugger it will automatically
send a state response packet. In this case, the target will re-enter
the debugger immediately after executing the next
instruction.</STRIKE></P>
<PRE><TT><STRIKE>#define sysPktSingleStepCmd 0x03</STRIKE></TT></PRE>
<CENTER><B><STRIKE>Figure 5 - Single Step
Command</STRIKE></B></CENTER>
<P>Note: there is no actual single step command implemented in either
the ROM or the Palm OS Emulator. Instead, this functionality is
performed by setting the trace bit in the Status Register and
executing a sysPktContinueCmd.</P>
<P> </P>
<H3><A NAME="Get Routine Name Command"></A>Get Routine Name
Command</H3>
<P>Figure 6 shows the structure of the request and response bodies
for the getRoutineName command. The host sends this command to
determine which routine a particular address is in. It will return
the starting and ending address of the routine and the name. The name
of each routine is imbedded into the code when it's compiled and the
target can determine the starting and ending address and name of the
routine by scanning forwards and backwards in the code for this
information.</P>
<PRE><TT>#define sysPktGetRtnNameCmd 0x04
#define sysPktGetRtnNameRsp 0x84
typedef struct SysPktRtnNameCmdType
{
_sysPktBodyCommon; // Common Body header
void* address; // -> address to query on
} SysPktRtnNameCmdType;
typedef struct SysPktRtnNameRspType
{
_sysPktBodyCommon; // Common Body header
void* address; // -> address to query on
void* startAddr; // <- start address of routine
void* endAddr; // <- end address of routine
char name[sysPktMaxNameLen]; // <- routine name, if any immediately
// follows the address range.
// The balance need not be sent.
} SysPktRtnNameRspType;</TT></PRE>
<CENTER><B>Figure 6 - Get Routine Name Command</B></CENTER>
<P>The address field in the response body is a copy of the address
sent in the request. The startAddr and endAddr fields are the
starting and ending address of the routine that includes address. The
name field is the 0 terminated name of the routine. If the target can
not determine which routine address is in, it will return 0 for the
first byte of the name in the response body and endAddr will contain
the last address that it scanned in trying to find out the routine
name. Subsequent getRoutineName calls should use the endAddr from the
previous call in order to look for more routines.</P>
<P> </P>
<H3><A NAME="Read Registers Command"></A>Read Registers Command</H3>
<P>Figure 7 shows the structure of the request and response bodies
for the readRegisters command. This command is sent by the host to
get the value of each of the processor registers on the target. The 8
data registers are stored in the packet body starting from D0. The 7
address registers are stored starting from A0.</P>
<PRE><TT>#define sysPktReadRegsCmd 0x05
#define sysPktReadRegsRsp 0x85
typedef struct SysPktReadRegsCmdTyp
{
_sysPktBodyCommon; // Common Body header
} SysPktReadRegsCmdType;
typedef struct SysPktReadRegsRspType
{
_sysPktBodyCommon; // Common Body header
M68KRegsType reg; // <- return registers
} SysPktReadRegsRspType;</TT></PRE>
<CENTER><B>Figure 7 - Read Registers Command</B></CENTER>
<P> </P>
<H3><A NAME="Write Registers Command"></A>Write Registers
Command</H3>
<P>Figure 8 shows the structure of the request and response bodies
for the writeRegisters command. This command is sent by the host to
set the value of each of the processor registers on the target. The 8
data registers are stored in the packet body starting from D0. The 7
address registers are stored starting from A0.</P>
<PRE><TT>#define sysPktWriteRegsCmd 0x06
#define sysPktWriteRegsRsp 0x86
typedef struct SysPktWriteRegsCmdType
{
_sysPktBodyCommon; // Common Body header
M68KRegsType reg; // -> registers to write
} SysPktWriteRegsCmdType;
typedef struct SysPktWriteRegsRspType
{
_sysPktBodyCommon; // Common Body header
} SysPktWriteRegsRspType;</TT></PRE>
<CENTER><B>Figure 8 - Write Registers Command</B></CENTER>
<P> </P>
<H3><A NAME="Continue Command"></A>Continue Command</H3>
<P>Figure 9 shows the structure of the request and response bodies
for the continue command. This command is sent by the host to tell
the target to continue execution. This is usually sent as a result of
the user entering the Go (g) command. The debugger on the target will
not get re-entered again unless a breakpoint or other exception is
encountered. The target does not send a response to this command. If
the target does re-enter the debugger due to a subsequent exception,
it will send a state response packet to the host.</P>
<PRE><TT>#define sysPktContinueCmd 0x07
typedef struct SysPktContinueCmdType
{
_sysPktBodyCommon; // Common Body header
M68KregsType regs; // registers
Boolean stepSpy; // set true to do step spy
DWord ssAddr; // step spy address
DWord ssCount; // # of bytes
DWord ssCheckSum; // checksum
} SysPktContinueCmdType;</TT></PRE>
<CENTER><B>Figure 9 - Continue Command</B></CENTER>
<P> </P>
<H3><A NAME="Get Breakpoints Command"></A>Get Breakpoints
Command</H3>
<P>Figure 10 shows the structure of the request and response bodies
for the getBreakpoints command. This command is sent by the host to
get the current settings of all target breakpoints. The response body
has an array of 6 breakpoints in it. If the enabled field for a
particular breakpoint entry is 0, it means that breakpoint is
disabled. If the address field is 0, it means that breakpoint is not
used. The installed field is currently never used.</P>
<PRE><TT>#define sysPktGetBreakpointsCmd 0x0B
#define sysPktGetBreakpointsRsp 0x8B
typedef struct SysPktGetBreakpointsCmdType
{
_sysPktBodyCommon; // Common Body header
} SysPktGetBreakpointsCmdType;
typedef struct SysPktGetBreakpointsRspType
{
_sysPktBodyCommon; // Common Body header
BreakpointType bp[dbgTotalBreakpoints];
} SysPktGetBreakpointsRspType;</TT></PRE>
<CENTER><B>Figure 10 - Get Breakpoints Command</B></CENTER>
<P> </P>
<H3><A NAME="Set Breakpoints Command"></A>Set Breakpoints
Command</H3>
<P>Figure 11 shows the structure of the request and response bodies
for the setBreakpoints command. This command is sent by the host to
set the target breakpoints. The request body has an array of 6
breakpoints in it. If the enabled field for a particular breakpoint
entry is 0, it means that breakpoint is disabled. If the address
field is 0, it means that breakpoint is not used.</P>
<PRE><TT>#define sysPktSetBreakpointsCmd 0x0C
#define sysPktSetBreakpointsRsp 0x8C
typedef struct SysPktSetTrapBreaksCmdType
{
_sysPktBodyCommon; // Common Body header
Word trapBP[dbgTotalTrapBreaks];
} SysPktSetTrapBreaksCmdType;
typedef struct SysPktSetTrapBreaksRspType
{
_sysPktBodyCommon; // Common Body header
} SysPktSetTrapBreaksRspType;</TT></PRE>
<CENTER><B>Figure 11 - Set Breakpoints Command</B></CENTER>
<P> </P>
<H3><A NAME="Toggle Debugger Breaks Command"></A>Toggle Debugger
Breaks Command</H3>
<P>Figure 12 shows the structure of the request and response bodies
for the toggleDbgBreaks command. This command is sent by the host to
enable or disable compiled-in breakpoints. A compiled in breakpoint
is a special TRAP instruction that gets compiled into the code with
the DbgBreak() and DbgSrcBreak() calls. The host can send this
command to tell the target whether or not to ignore these
breakpoints. The request toggles the state and the response returns
the new state (non-zero for enabled, 0 for disabled).</P>
<PRE><TT>#define sysPktDbgBreakToggleCmd 0x0D
#define sysPktDbgBreakToggleRsp 0x8D
typedef struct SysPktDbgBreakToggleCmdType
{
_sysPktBodyCommon; // Common Body header
} SysPktDbgBreakToggleCmdType;
typedef struct SysPktDbgBreakToggleRspType
{
_sysPktBodyCommon; // Common Body header
Boolean newState;
} SysPktDbgBreakToggleRspType;</TT></PRE>
<CENTER><B>Figure 12 - Toggle Debugger Breaks Command</B></CENTER>
<P> </P>
<H3><A NAME="Get Trap Breaks Command"></A>Get Trap Breaks
Command</H3>
<P>Figure 13 shows the structure of the request and response bodies
for the getTrapBreaks command. The host sends this command to get the
current settings of all target trap breaks. The response body has an
array of 5 traps in it. If the trap field is 0, it means that trap
break is not used. Trap breaks are used to force the target to enter
the debugger when a particular system trap is called. Up to 5 trap
breaks can be set at any time.</P>
<PRE>#define sysPktGetTrapBreaksCmd 0x10
#define sysPktGetTrapBreaksRsp 0x90
typedef struct SysPktGetTrapBreaksCmdType
{
_sysPktBodyCommon; // Common Body header
} SysPktGetTrapBreaksCmdType;
typedef struct SysPktGetTrapBreaksRspType
{
_sysPktBodyCommon; // Common Body header
Word trapBP[dbgTotalTrapBreaks];
} SysPktGetTrapBreaksRspType;</PRE>
<CENTER><B>Figure 13 - Get Trap Breaks Command</B></CENTER>
<H3><A NAME="Set Trap Breaks Command"></A>Set Trap Breaks
Command</H3>
<P>Figure 14 shows the structure of the request and response bodies
for the setTrapBreaks command. The host sends this command to set the
current settings of all target trap breaks. The request body has an
array of 5 traps in it. If the trap field is 0, it means that trap
break is not used. Trap breaks are used to force the target to enter
the debugger when a particular system trap is called. Up to 5 trap
breaks can be set at any time.</P>
<PRE>#define sysPktSetTrapBreaksCmd 0x11
#define sysPktSetTrapBreaksRsp 0x91
typedef struct SysPktSetTrapBreaksCmdType
{
_sysPktBodyCommon; // Common Body header
Word trapBP[dbgTotalTrapBreaks];
} SysPktSetTrapBreaksCmdType;
typedef struct SysPktSetTrapBreaksRspType
{
_sysPktBodyCommon; // Common Body header
} SysPktSetTrapBreaksRspType;</PRE>
<CENTER><B>Figure 14 - Set Trap Breaks Command</B></CENTER>
<H3><A NAME="Find Command"></A>Find Command</H3>
<P>Figure 15 shows the structure of the request and response bodies
for the find command. This command is sent by the host to search for
data on the target. The firstAddr and lastAddr fields of the request
set the range of addresses to search through. The numBytes field
contains the number of bytes in the search string. If the
caseInsensitive byte is non-zero, a case-insensitive search will be
made. The variable length search string follows the caseInsensitive
field.</P>
<P>In the response body, addrFound contains the address of the found
data. If the data was not found, the found field will be 0.</P>
<PRE>#define sysPktFindCmd 0x13
#define sysPktFindRsp 0x93
typedef struct SysPktFindCmdType
{
_sysPktBodyCommon; // Common Body header
DWord firstAddr; // first address to search
DWord lastAddr; // last address to begin searching
Word numBytes; // number of data bytes to match
Boolean caseInsensitive; // if true, perform a case-insensitive search
} SysPktFindCmdType;
typedef struct SysPktFindRspType
{
_sysPktBodyCommon; // Common Body header
DWord addr; // address where data was found
Boolean found; // true if data was found
} SysPktFindRspType;</PRE>
<CENTER><B>Figure 15 - Find Command</B></CENTER>
<H3><A NAME="Message Command"></A>Message Command</H3>
<P>Figure 16 shows the structure of the message packet body. This
packet is sent by the target to display a message on the host.
Debugger messages can be compiled into the source code through the
DbgMessage() call. They can be used by applications on Palm devices
for displaying application specific debugging messages during
execution. There is no response sent back from the host to the target
when it receives one of these packets.</P>
<PRE>#define sysPktRemoteMsgCmd 0x7F
typedef struct SysPktRemoteMsgCmdType
{
_sysPktBodyCommon; // Common Body header
Byte text[1]; // variable length text goes here
} SysPktRemoteMsgCmdType;</PRE>
<CENTER><B>Figure 16 - Message Command</B></CENTER>
<H3><A NAME="RPC Command"></A>RPC Command</H3>
<PRE>#define sysPktRPCCmd 0x0A
#define sysPktRPCRsp 0x8A
typedef struct SysPktRPCParamInfo
{
Byte byRef; // true if param is by reference
Byte size; // # of Bytes of paramData (must be even)
Word data[1]; // variable length array of paramData
} SysPktRPCParamType;
typedef struct SysPktRPCType
{
_sysPktBodyCommon; // Common Body header
Word trapWord; // which trap to execute
Dword resultD0; // result from D0 placed here
Dword resultA0; // result from A0 placed here
Word numParams; // how many parameters follow
// Following is a variable length array of SysPktRPCParamType's
SysPktRPCParamType param[1];
} SysPktRPCType;</PRE>
<CENTER><B>Figure 17 - RPC Command</B></CENTER>
<H3><A NAME="Get Trap Conditionals Command"></A>Get Trap Conditionals
Command (new in 3.0)</H3>
<P>These are used to tell the debugger to conditionally break on a
trap depending on the value of the first word on the stack. They are
used when setting a-traps on library calls.</P>
<PRE>#define sysPktGetTrapConditionsCmd 0x14
#define sysPktGetTrapConditionsRsp 0x94
typedef struct SysPktGetTrapConditionsCmdType
{
_sysPktBodyCommon; // Common Body header
} SysPktGetTrapConditionsCmdType;
typedef struct SysPktGetTrapConditionsRspType
{
_sysPktBodyCommon; // Common Body header
Word trapParam[dbgTotalTrapBreaks];
} SysPktGetTrapConditionsRspType;</PRE>
<CENTER><B>Figure 18 - Get Trap Conditionals Command</B></CENTER>
<H3><A NAME="Set Trap Conditionals Command"></A>Set Trap Conditionals
Command (new in 3.0)</H3>
<P>These are used to tell the debugger to conditionally break on a
trap depending on the value of the first word on the stack. They are
used when setting a-traps on library calls.</P>
<PRE>#define sysPktSetTrapConditionsCmd 0x15
#define sysPktSetTrapConditionsRsp 0x95
typedef struct SysPktSetTrapConditionsCmdType
{
_sysPktBodyCommon; // Common Body header
Word trapParam[dbgTotalTrapBreaks];
} SysPktSetTrapConditionsCmdType;
typedef struct SysPktSetTrapConditionsRspType
{
_sysPktBodyCommon; // Common Body header
} SysPktSetTrapConditionsRspType;</PRE>
<CENTER><B>Figure 19 - Set Trap Conditionals Command</B></CENTER>
<P> </P>
</BODY>
</HTML>
|
