aboutsummaryrefslogtreecommitdiff
path: root/gdb/rdi-share/armdbg.h
blob: b5fae113281d6ec7f39558f5840b145363f16458 (plain)
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
/* 
 * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
 * 
 * This software may be freely used, copied, modified, and distributed
 * provided that the above copyright notice is preserved in all copies of the
 * software.
 */

/*
 * ARM symbolic debugger toolbox interface
 */

/*
 * RCS $Revision$
 * Checkin $Date$
 */

/* Minor points of uncertainty are indicated by a question mark in the
   LH margin.

   Wherever an interface is required to iterate over things of some class,
   I prefer something of the form  EnumerateXXs(..., XXProc *p, void *arg)
   which results in a call of p(xx, arg) for each xx, rather than something
   of the form
     for (xxh = StartIterationOverXXs(); (xx = Next(xxh)) != 0; ) { ... }
     EndIterationOverXXs(xxh);
   Others may disagree.
   (Each XXProc returns an Error value: if this is not Err_OK, iteration
   stops immediately and the EnumerateXXs function returns that value).

   ptrace has been retired as of insufficient utility.  If such fuctionality is
   required, it can be constructed using breakpoints.

   The file form of all name fields in debug areas is in-line, with a length
   byte and no terminator.  The debugger toolbox makes an in-store translation,
   where the strings are out of line (the namep variant in asdfmt.h) and have a
   terminating zero byte: the pointer is to the first character of the string
   with the length byte at ...->n.namep[-1].
 */

#ifndef armdbg__h
#define armdbg__h

#include <stddef.h>

#include "host.h"
#include "msg.h"

typedef unsigned32 ARMaddress;
typedef unsigned32 ARMword;
typedef unsigned16 ARMhword;

#include "dbg_conf.h"
#include "dbg_rdi.h"

#ifdef __cplusplus
extern "C"
{
#endif

typedef unsigned char Dbg_Byte;

typedef int Dbg_Error;

typedef struct Dbg_MCState Dbg_MCState;
/* A representation of the state of the target.  The structure is not revealed.
   A pointer to one of these is returned by Dbg_Initialise(), is passed to all
   toolbox calls which refer to the state of the target, and is discarded
   by Dbg_Finalise().
   Nothing in the toolbox itself precludes there being multiple targets, each
   with its own state.
 */

/* Most toolbox interfaces return an error status.  Only a few of the status
   values are expected to be interesting to clients and defined here; the
   rest are private (but a textual form can be produced by ErrorToChars()).
 */

#define Error_OK 0

/* Partitioning of the error code space: errors below Dbg_Error_Base are RDI
   errors (as defined in dbg_rdi.h). Codes above Dbg_Error_Limit are
   available to clients, who may impose some further structure.
 */
#define Dbg_Error_Base 0x1000
#define Dbg_Error_Limit 0x2000

#define DbgError(n) ((Dbg_Error)(Dbg_Error_Base+(n)))

#define Dbg_Err_OK Error_OK
#define Dbg_Err_Interrupted             DbgError(1)
#define Dbg_Err_Overflow                DbgError(2)
#define Dbg_Err_FileNotFound            DbgError(3)
#define Dbg_Err_ActivationNotPresent    DbgError(4)
#define Dbg_Err_OutOfHeap               DbgError(5)
#define Dbg_Err_TypeNotSimple           DbgError(6)
#define Dbg_Err_BufferFull              DbgError(7)
#define Dbg_Err_AtStackBase             DbgError(8)
#define Dbg_Err_AtStackTop              DbgError(9)
#define Dbg_Err_DbgTableFormat          DbgError(10)
#define Dbg_Err_NotVariable             DbgError(11)
#define Dbg_Err_NoSuchBreakPoint        DbgError(12)
#define Dbg_Err_NoSuchWatchPoint        DbgError(13)
#define Dbg_Err_FileLineNotFound        DbgError(14)
#define Dbg_Err_DbgTableVersion         DbgError(15)
#define Dbg_Err_NoSuchPath              DbgError(16)
#define Dbg_Err_StateChanged            DbgError(17)
#define Dbg_Err_SoftInitialiseError     DbgError(18)
#define Dbg_Err_CoProRegNotWritable     DbgError(19)
#define Dbg_Err_NotInHistory            DbgError(20)
#define Dbg_Err_ContextSyntax           DbgError(21)
#define Dbg_Err_ContextNoLine           DbgError(22)
#define Dbg_Err_ContextTwoLines         DbgError(23)
#define Dbg_Err_VarReadOnly             DbgError(24)
#define Dbg_Err_FileNewerThanImage      DbgError(25)
#define Dbg_Err_NotFound                DbgError(26)

   /* functions which evaluate expressions may return this value, to indicate
      that execution became suspended within a function called in the debugee */

/* Functions returning characters take a BufDesc argument, with fields buffer
   and bufsize being input arguments describing the buffer to be filled, and
   filled being set on return to the number of bytes written to the buffer
   (omitting the terminating 0).
 */

typedef struct Dbg_BufDesc Dbg_BufDesc;

typedef void Dbg_BufferFullProc(Dbg_BufDesc *bd);

struct Dbg_BufDesc {
    char *buffer;
    size_t size,
           filled;
    Dbg_BufferFullProc *p;
    void *arg;
};

#define Dbg_InitBufDesc(bd, buf, bytes) \
    ((bd).buffer = (buf), (bd).size = (bytes), (bd).filled = 0,\
     (bd).p = NULL, (bd).arg = NULL)

#define Dbg_InitBufDesc_P(bd, buf, bytes, fn, a) \
    ((bd).buffer = (buf), (bd).size = (bytes), (bd).filled = 0,\
     (bd).p = (fn), (bd).arg = (a))

Dbg_Error Dbg_StringToBuf(Dbg_BufDesc *buf, char const *s);
Dbg_Error Dbg_BufPrintf(Dbg_BufDesc *buf, char const *form, ...);
#ifdef NLS
Dbg_Error Dbg_MsgToBuf(Dbg_BufDesc *buf, msg_t t);
Dbg_Error Dbg_BufMsgPrintf(Dbg_BufDesc *buf, msg_t form, ...);
#else
#define Dbg_MsgToBuf Dbg_StringToBuf
#define Dbg_BufMsgPrintf Dbg_BufPrintf
#endif
Dbg_Error Dbg_CharToBuf(Dbg_BufDesc *buf, int ch);

int Dbg_CIStrCmp(char const *s1, char const *s2);
/* Case-independent string comparison, interface as for strcmp */

int Dbg_CIStrnCmp(char const *s1, char const *s2, size_t n);
/* Case-independent string comparison, interface as for strncmp */

void Dbg_ErrorToChars(Dbg_MCState *state, Dbg_Error err, Dbg_BufDesc *buf);

typedef int Dbg_RDIResetCheckProc(int);
/* Type of a function to be called after each RDI operation performed by the
   toolbox, with the status from the operation as argument.  The value returned
   is treated as the status.  (The intent is to allow the toolbox's client to
   take special action to handle RDIDbg_Error_Reset).
 */

typedef struct Dbg_CoProDesc Dbg_CoProDesc;

typedef Dbg_Error Dbg_CoProFoundProc(Dbg_MCState *state, int cpno, Dbg_CoProDesc const *cpd);
/* Type of a function to be called when the shape of a coprocessor is discovered
   by enquiry of the target or agent (via RequestCoProDesc)
 */

typedef struct RDIProcVec RDIProcVec;

Dbg_Error Dbg_RequestReset(Dbg_MCState *);

Dbg_Error Dbg_Initialise(
    Dbg_ConfigBlock *config, Dbg_HostosInterface const *i,
    Dbg_RDIResetCheckProc *checkreset, Dbg_CoProFoundProc *coprofound,
    RDIProcVec const *rdi, Dbg_MCState **statep);
/* values in config are updated if they call for default values */

void Dbg_Finalise(Dbg_MCState *state, bool targetdead);

typedef struct {
    char name[16];
    RDI_MemDescr md;
    RDI_MemAccessStats a;
} Dbg_MemStats;

/*--------------------------------------------------------------------------*/

/* Symbol table management.
   The structure of a Dbg_SymTable is not revealed.  It is created by
   Dbg_ReadSymbols() or by Dbg_LoadFile(), and associated with the argument
   Dbg_MCState.
   Many symbol tables may be concurrently active.
   A Dbg_SymTable is removed either explicitly (by call to Dbg_DeleteSymbols)
   or implicitly when a symbol table for an overlapping address range is read.

   There is a pre-defined symbol table containing entries for ARM registers,
   co-processor registers and the like.
 */

typedef struct Dbg_SymTable Dbg_SymTable;

typedef struct Dbg_ImageFragmentDesc {
    ARMaddress base, limit;
} Dbg_ImageFragmentDesc;

typedef enum {
    Dbg_Lang_None,
    Dbg_Lang_C,
    Dbg_Lang_Pascal,
    Dbg_Lang_Fortran,
    Dbg_Lang_Asm,
    Dbg_Lang_Cpp
} Dbg_Lang;

typedef struct Dbg_ImageDesc {
    Dbg_Lang lang;
    int executable;
    ARMaddress robase, rolimit, rwbase, rwlimit;
    int nfrags;
    Dbg_ImageFragmentDesc *fragments;
    char *name;
} Dbg_ImageDesc;

Dbg_ImageDesc *Dbg_ImageAreas(Dbg_SymTable *st);

Dbg_SymTable *Dbg_LastImage(Dbg_MCState *state);

Dbg_SymTable *Dbg_NewSymTable(Dbg_MCState *state, const char *name);

Dbg_Error Dbg_ReadSymbols(Dbg_MCState *state, const char *filename, Dbg_SymTable **st);
/* Just read the symbols from the named image.  <st> is set to the allocated
   symbol table.
?  Maybe we could usefully allow other formats than AIF images to describe
   the symbols (eg) of shared libraries
 */

typedef struct Dbg_SymInfo {
    int isize;
    ARMaddress addr;
    char *name;
} Dbg_SymInfo;

Dbg_SymInfo *Dbg_AsmSym(Dbg_SymTable *st, ARMaddress addr);
int32 Dbg_AsmAddr(Dbg_SymTable *st, int32 line);
int32 Dbg_AsmLine(Dbg_SymTable *st, ARMaddress addr);
int32 Dbg_AsmLinesInRange(Dbg_SymTable *st, ARMaddress start, ARMaddress end);

Dbg_Error Dbg_LoadFile(Dbg_MCState *state, const char *filename, Dbg_SymTable **st);
/* load the image into target memory, and read its symbols.  <st> is set to
   the allocated symbol table.
   A null filename reloads the most recently loaded file (and rereads its
   symbols).
   Loading an image leaves breakpoints unchanged.  If a client wishes
   otherwise, it must remove the breakpoints explicitly.
*/

Dbg_Error Dbg_CallGLoadFile(Dbg_MCState *state, const char *filename, Dbg_SymTable **st);

typedef void Dbg_ImageLoadProc(Dbg_MCState *, Dbg_SymTable *);
Dbg_Error Dbg_OnImageLoad(Dbg_MCState *, Dbg_ImageLoadProc *);
/* Register function to be called back whenever an image is loaded, or symbols
 * for an image read. (To allow multiple toolbox clients to coexist).
 */

Dbg_Error Dbg_LoadAgent(Dbg_MCState *state, const char *filename);
/* Load a debug agent, and start it.
   Symbols in the image for the agent are ignored.
*/

Dbg_Error Dbg_RelocateSymbols(Dbg_SymTable *st, ARMaddress reloc);
/* add <reloc> to the value of all symbols in <st> describing absolute memory
   locations.  The intent is to allow the symbols in a load-time relocating
   image (for example) to be useful.
 */

Dbg_Error Dbg_DeleteSymbols(Dbg_MCState *state, Dbg_SymTable **st);

typedef enum Dbg_LLSymType {
    llst_code,
    llst_code16,
    llst_data,
    llst_const,
    llst_unknown,
    llst_max
} Dbg_LLSymType;
/* Since AIF images contain no type information for low-level symbols, this
   classification is only a guess, and some symbols describing constants will
   incorrectly be described as code or data.
 */

typedef Dbg_Error Dbg_SymProc(
    Dbg_MCState *state,
    const char *symbol, Dbg_LLSymType symtype, ARMaddress value,
    void *arg);

Dbg_Error Dbg_EnumerateLowLevelSymbols(
    Dbg_MCState *state, const char *match, Dbg_SymProc *p,
    void *arg);
/* Call  p(name, value)  for each low level symbol in the tables of <state>
   whose name matches the regular expression <match> (a NULL <match> matches
   any name).  Symbols are enumerated in no particular order.
 */

/*--------------------------------------------------------------------------*/

/* Functions are provided here to allow quick mass access to register values
   for display.  There is no comparable need for quick mass update, so writing
   should be via Assign().
 */

typedef struct Dbg_RegSet {
    ARMword
        user[15],
        pc,
        psr,
        fiq[7],
        spsr_fiq,
        irq[2],
        spsr_irq,
        svc[2],
        spsr_svc,
        abort[2],
        spsr_abort,
        undef[2],
        spsr_undef;
} Dbg_RegSet;

/* bits in the modemask argument for ReadRegisters */

#define Dbg_MM_User     1
#define Dbg_MM_FIQ      2
#define Dbg_MM_IRQ      4
#define Dbg_MM_SVC      8
#define Dbg_MM_Abort 0x10
#define Dbg_MM_Undef 0x20
#define Dbg_MM_System 0x40

Dbg_Error Dbg_ReadRegisters(Dbg_MCState *state, Dbg_RegSet *regs, int modemask);

Dbg_Error Dbg_WriteRegister(Dbg_MCState *state, int rno, int modemask, ARMword val);

int Dbg_StringToMode(const char *name);

int Dbg_ModeToModeMask(ARMword mode);

/* Some implementations of the FP instruction set keep FP values loaded into
   registers in their unconverted format, converting only when necessary.
   Some RDI implementations deliver these values uninterpreted.
   (For the rest, register values will always have type F_Extended).
 */

typedef enum { F_Single, F_Double, F_Extended, F_Packed, /* fpe340 values */
               F_Internal,                               /* new fpe : mostly as extended */
               F_None } Dbg_FPType;

typedef struct { ARMword w[3]; } Dbg_TargetExtendedVal;
typedef struct { ARMword w[3]; } Dbg_TargetPackedVal;
typedef struct { ARMword w[2]; } Dbg_TargetDoubleVal;
typedef struct { ARMword w[1]; } Dbg_TargetFloatVal;

typedef union { Dbg_TargetExtendedVal e; Dbg_TargetPackedVal p;
                Dbg_TargetDoubleVal d; Dbg_TargetFloatVal f; } Dbg_TargetFPVal;

#define TargetSizeof_Extended 12
#define TargetSizeof_Packed   12
#define TargetSizeof_Double   8
#define TargetSizeof_Float    4

typedef struct Dbg_FPRegVal {
     Dbg_FPType type;
     Dbg_TargetFPVal v;
} Dbg_FPRegVal;

typedef struct Dbg_FPRegSet {
    Dbg_FPRegVal f[8];
    ARMword fpsr, fpcr;
} Dbg_FPRegSet;

Dbg_Error Dbg_ReadFPRegisters(Dbg_MCState *state, Dbg_FPRegSet *regs);

Dbg_Error Dbg_WriteFPRegisters(Dbg_MCState *state, int32 mask, Dbg_FPRegSet *regs);

Dbg_Error Dbg_FPRegToDouble(DbleBin *d, Dbg_FPRegVal const *f);
/* Converts from a FP register value (in any format) to a double with
   approximately the same value (or returns Dbg_Err_Overflow)
 */

void Dbg_DoubleToFPReg(Dbg_FPRegVal *f, DbleBin const *d);
/* Converts the double <d> to a Dbg_FPRegVal with type F_Extended */

/*--------------------------------------------------------------------------*/

#include "dbg_cp.h"

Dbg_Error Dbg_DescribeCoPro(Dbg_MCState *state, int cpnum, Dbg_CoProDesc *p);

Dbg_Error Dbg_DescribeCoPro_RDI(Dbg_MCState *state, int cpnum, Dbg_CoProDesc *p);

Dbg_Error Dbg_ReadCPRegisters(Dbg_MCState *state, int cpnum, ARMword *regs);

Dbg_Error Dbg_WriteCPRegisters(Dbg_MCState *state, int cpnum, int32 mask, ARMword *regs);

/*--------------------------------------------------------------------------*/

Dbg_Error Dbg_ReadWords(
    Dbg_MCState *state,
    ARMword *words, ARMaddress addr, unsigned count);
/* Reads a number of (32-bit) words from target store.  The values are in host
   byte order; if they are also to be interpreted as bytes Dbg_SwapByteOrder()
   must be called to convert to target byte order.
 */

Dbg_Error Dbg_WriteWords(
    Dbg_MCState *state,
    ARMaddress addr, const ARMword *words, unsigned count);
/* Writes a number of (32-bit) words to target store.  The values are in host
   byte order (if what is being written is actually a byte string it must be
   converted by Dbg_SwapByteOrder()).
 */

Dbg_Error Dbg_ReadHalf(Dbg_MCState *state, ARMhword *val, ARMaddress addr);
Dbg_Error Dbg_WriteHalf(Dbg_MCState *state, ARMaddress addr, ARMword val);

Dbg_Error Dbg_ReadBytes(Dbg_MCState *state, Dbg_Byte *val, ARMaddress addr, unsigned count);
Dbg_Error Dbg_WriteBytes(Dbg_MCState *state, ARMaddress addr, const Dbg_Byte *val, unsigned count);

void Dbg_HostWords(Dbg_MCState *state, ARMword *words, unsigned wordcount);
/* (A noop unless host and target bytesexes differ) */

ARMword Dbg_HostWord(Dbg_MCState *state, ARMword v);

ARMhword Dbg_HostHalf(Dbg_MCState *state, ARMword v);

/*--------------------------------------------------------------------------*/

/* Types describing various aspects of position within code.
   There are rather a lot of these, in the interests of describing precisely
   what fields must be present (rather than having a single type with many
   fields which may or may not be valid according to context).
 */

typedef struct Dbg_LLPos {
    Dbg_SymTable *st;
    char *llsym;
    ARMaddress offset;
} Dbg_LLPos;

typedef struct Dbg_File {
    Dbg_SymTable *st;
    char *file;
} Dbg_File;

typedef struct Dbg_Line {
    unsigned32 line;      /* linenumber in the file */
    unsigned16 statement, /* within the line (1-based) */
               charpos;   /* ditto */
} Dbg_Line;
/* As an output value from toolbox functions, both statement and charpos are set
   if the version of the debugger tables for the section concerned permits.
   On input, <charpos> is used only if <statement> is 0 (in which case, if
   <charpos> is non-0, Dbg_Err_DbgTableVersion is returned if the version of
   the debugger tables concerned is too early.
 */

typedef struct Dbg_FilePos {
    Dbg_File f;
    Dbg_Line line;
} Dbg_FilePos;

typedef struct Dbg_ProcDesc {
    Dbg_File f;
    char *name;
} Dbg_ProcDesc;

typedef struct Dbg_ProcPos {
    Dbg_ProcDesc p;
    Dbg_Line line;
} Dbg_ProcPos;

/* Support for conversions between position representations */

Dbg_Error Dbg_ProcDescToLine(Dbg_MCState *state, Dbg_ProcDesc *proc, Dbg_Line *line);
/* If proc->f.file is null (and there is just one function proc->name), it is
   updated to point to the name of the file containing (the start of)
   proc->name.
 */

Dbg_Error Dbg_FilePosToProc(Dbg_MCState *state, const Dbg_FilePos *pos, char **procname);

/* Conversions from position representations to and from code addresses */

Dbg_Error Dbg_AddressToProcPos(
    Dbg_MCState *state, ARMaddress addr,
    Dbg_ProcPos *pos);
Dbg_Error Dbg_AddressToLLPos(
    Dbg_MCState *state, ARMaddress addr,
    Dbg_LLPos *pos, Dbg_LLSymType *res_type, int system_names);

Dbg_Error Dbg_ProcPosToAddress(
    Dbg_MCState *state, const Dbg_ProcPos *pos,
    ARMaddress *res);
Dbg_Error Dbg_LLPosToAddress(
    Dbg_MCState *state, const Dbg_LLPos *pos,
    ARMaddress *res);

typedef struct {
    ARMaddress start, end;
} Dbg_AddressRange;

typedef Dbg_Error Dbg_AddressRangeProc(void *arg, int32 first, int32 last, Dbg_AddressRange const *range);

Dbg_Error Dbg_MapAddressRangesForFileRange(
    Dbg_MCState *state,
    Dbg_SymTable *st, const char *f, int32 first, int32 last, Dbg_AddressRangeProc *p, void *arg);

typedef struct Dbg_Environment Dbg_Environment;
/* A Dbg_Environment describes the context required to make sense of a variable
   name and access its value.  Its format is not revealed.  Dbg_Environment
   values are allocated by Dbg_NewEnvironment() and discarded by
   Dbg_DeleteEnvironment().
 */

Dbg_Environment *Dbg_NewEnvironment(Dbg_MCState *state);
void Dbg_DeleteEnvironment(Dbg_MCState *state, Dbg_Environment *env);

Dbg_Error Dbg_StringToEnv(
    Dbg_MCState *state, char *str, Dbg_Environment *resenv,
    int forcontext, Dbg_Environment const *curenv);

Dbg_Error Dbg_ProcPosToEnvironment(
    Dbg_MCState *state, const Dbg_ProcPos *pos, int activation,
    const Dbg_Environment *current, Dbg_Environment *res);

/* Conversion from a position representation to an Dbg_Environment (as required
   to access variable values).  Only a Dbg_ProcPos argument here; other
   representations need to be converted first.

   Returns <res> describing the <activation>th instance of the function
   described by <pos>, up from the stack base if <activation> is negative,
   else down from <current>.
   If this function returns Dbg_Err_ActivationNotPresent, the result
   Dbg_Environment is still valid for accessing non-auto variables.
 */

typedef struct Dbg_DeclSpec Dbg_DeclSpec;

Dbg_Error Dbg_EnvToProcItem(
    Dbg_MCState *state, Dbg_Environment const *env, Dbg_DeclSpec *proc);

Dbg_Error Dbg_ContainingEnvironment(
    Dbg_MCState *state, const Dbg_Environment *context, Dbg_Environment *res);
/* Set <res> to describe the containing function, file if <context> is within
   a top-level function (or error if <context> already describes a file).
 */

/*--------------------------------------------------------------------------*/

/* ASD debug table pointers are not by themselves sufficient description,
   since there's an implied section context.  Hence the DeclSpec and TypeSpec
   structures.
 */


#ifndef Dbg_TypeSpec_Defined

struct Dbg_DeclSpec { void *a; };

#ifdef CALLABLE_COMPILER
typedef void *Dbg_TypeSpec;

/* The intention here is to give an alternative definition for Dbg_BasicType
   which follows.
 */

#define Dbg_T_Void      xDbg_T_Void
#define Dbg_T_Bool      xDbg_T_Bool
#define Dbg_T_SByte     xDbg_T_SByte
#define Dbg_T_SHalf     xDbg_T_Half
#define Dbg_T_SWord     xDbg_T_SWord
#define Dbg_T_UByte     xDbg_T_UByte
#define Dbg_T_UHalf     xDbg_T_UHalf
#define Dbg_T_UWord     xDbg_T_UWord
#define Dbg_T_Float     xDbg_T_Float
#define Dbg_T_Double    xDbg_T_Double
#define Dbg_T_LDouble   xDbg_T_LDouble
#define Dbg_T_Complex   xDbg_T_Complex
#define Dbg_T_DComplex  xDbg_T_DComplex
#define Dbg_T_String    xDbg_T_String
#define Dbg_T_Function  xDbg_T_Function

#define Dbg_BasicType   xDbg_BaiscType
#define Dbg_PrimitiveTypeToTypeSpec xDbg_PrimitiveTypeToTypeSpec

#else
/* We want a Dbg_TypeSpec to be a an opaque type, but of known size (so the
   toolbox's clients can allocate the store to hold one); unfortunately, we
   can do this only by having one definition for the toolbox's clients and
   one (elsewhere) for the toolbox itself.
 */

typedef struct Dbg_TypeSpec Dbg_TypeSpec;
struct Dbg_TypeSpec { void *a; int32 b; };
#endif /* CALLABLE_COMPILER */

typedef enum {
    Dbg_T_Void,

    Dbg_T_Bool,

    Dbg_T_SByte,
    Dbg_T_SHalf,
    Dbg_T_SWord,

    Dbg_T_UByte,
    Dbg_T_UHalf,
    Dbg_T_UWord,

    Dbg_T_Float,
    Dbg_T_Double,
    Dbg_T_LDouble,

    Dbg_T_Complex,
    Dbg_T_DComplex,

    Dbg_T_String,

    Dbg_T_Function
} Dbg_BasicType;

#endif

void Dbg_PrimitiveTypeToTypeSpec(Dbg_TypeSpec *ts, Dbg_BasicType t);

bool Dbg_TypeIsIntegral(Dbg_TypeSpec const *ts);

bool Dbg_TypeIsPointer(Dbg_TypeSpec const *ts);

bool Dbg_TypeIsFunction(Dbg_TypeSpec const *ts);

bool Dbg_PruneType(Dbg_TypeSpec *tsres, Dbg_TypeSpec const *ts);
/* Return to tsres a version of ts which has been pruned by the removal of all
   toplevel typedefs. Result is YES if the result has changed.
 */

typedef Dbg_Error Dbg_FileProc(Dbg_MCState *state, const char *name, const Dbg_DeclSpec *procdef, void *arg);

Dbg_Error Dbg_EnumerateFiles(Dbg_MCState *state, Dbg_SymTable *st, Dbg_FileProc *p, void *arg);
/* The top level for a high level enumerate.  Lower levels are performed by
   EnumerateDeclarations (below).
 */

typedef enum {
    ds_Invalid,
    ds_Type,
    ds_Var,
    ds_Proc,
    ds_Enum,
    ds_Function,
    ds_Label
} Dbg_DeclSort;

Dbg_DeclSort Dbg_SortOfDeclSpec(Dbg_DeclSpec const *decl);

char *Dbg_NameOfDeclSpec(Dbg_DeclSpec const *decl);

Dbg_TypeSpec Dbg_TypeSpecOfDeclSpec(Dbg_DeclSpec const *decl);

typedef enum {
    cs_None,
    cs_Extern,
    cs_Static,
    cs_Auto,
    cs_Reg,
    cs_Var,
    cs_Farg,
    cs_Fcarg,
    cs_Local,
    cs_Filtered,
    cs_Globalreg
} Dbg_StgClass;

Dbg_StgClass Dbg_StgClassOfDeclSpec(Dbg_DeclSpec const *decl);

bool Dbg_VarsAtSameAddress(Dbg_DeclSpec const *d1, Dbg_DeclSpec const *d2);

bool Dbg_VarsDecribedForDeclSpec(Dbg_DeclSpec const *decl);

int Dbg_ArgCountOfDeclSpec(Dbg_DeclSpec const *decl);

typedef struct Dbg_DComplex { DbleBin r, i; } Dbg_DComplex;

typedef union Dbg_ConstantVal {
    int32 l;
    unsigned32 u;
    DbleBin d;
    Dbg_DComplex fc;
    ARMaddress a;
    char *s;
} Dbg_ConstantVal;

typedef struct Dbg_Constant {
    Dbg_TypeSpec type;
    Dbg_ConstantVal val;
} Dbg_Constant;

typedef enum Dbg_ValueSort {
    vs_register,
    vs_store,
    vs_constant,
    vs_local,
    vs_filtered,
    vs_none,
    vs_error
} Dbg_ValueSort;

/* vs_local allows the use of symbol table entries to describe entities within
   the debugger's own address space, accessed in the same way as target
   variables.
   vs_filtered describes entities which may be read or written only via an
   access function (eg r15)
 */

#define fpr_base 16
/* There's only one register ValueSort (reflecting asd table StgClass);
   fp register n is encoded as register n+fpr_base.
 */

typedef struct Dbg_Value Dbg_Value;

typedef Dbg_Error Dbg_AccessFn(Dbg_MCState *state, int write, Dbg_Value *self, Dbg_Constant *c);
/* <write> == 0: read a vs_filtered value, updating the value self.
   <write> == 1: update a vs_filtered value, with the value described by c.
   <self> allows use of the same Dbg_AccessFn for several different entities
   (using different val.f.id fields).
 */

typedef Dbg_Error Dbg_FormatFn(int decode, char *b, ARMword *valp, void *formatarg);

typedef struct { Dbg_AccessFn *f; int id; } Dbg_AccessFnRec;

struct Dbg_Value {
    Dbg_TypeSpec type;
    Dbg_ValueSort sort;
    Dbg_FormatFn *formatp;
    void *formatarg;
    int f77csize;
    union {
        struct { int no; ARMaddress frame; } r;
        ARMaddress ptr;
        Dbg_ConstantVal c;
        void *localp;
        Dbg_AccessFnRec f;
        Dbg_Error err;
    } val;
};

Dbg_Error Dbg_AddLLSymbol(Dbg_SymTable *st, char const *name, Dbg_LLSymType type, ARMword val);

Dbg_Error Dbg_AddSymbol(Dbg_SymTable *st, char const *name, Dbg_Value const *val);

typedef struct Dbg_DeclSpecF {
  Dbg_DeclSpec decl;
  Dbg_FormatFn *formatp;
  void *formatarg;
} Dbg_DeclSpecF;

typedef Dbg_Error Dbg_DeclProc(Dbg_MCState *state, Dbg_Environment const *context,
                       Dbg_DeclSpecF const *var, Dbg_DeclSort sort, int masked,
                       void *arg);

Dbg_Error Dbg_EnumerateDeclarations(Dbg_MCState *state, Dbg_Environment const *context,
                            Dbg_DeclProc *p, void *arg);
/* call p once for every declaration local to the function described by
   <context> (or file if <context> describes a place outside a function).
   p's argument <masked> is true if the variable is not visible, thanks to
   a declaration in an inner scope.
 */

Dbg_Error Dbg_ValueOfVar(Dbg_MCState *state, const Dbg_Environment *context,
                 const Dbg_DeclSpec *var, Dbg_Value *val);
/* Different from Dbg_EvalExpr() in that the thing being evaluated is described
   by a Dbg_DeclSpec (which must be for a variable), rather than a string
   needing to be decoded and associated with a symbol-table item.  Intended to
   be called from a Dbg_DeclProc called from Dbg_EnumerateDeclarations.
 */

Dbg_Error Dbg_EvalExpr(Dbg_MCState *state, Dbg_Environment const *context,
               char const *expr, int flags, Dbg_Value *val);

Dbg_Error Dbg_EvalExpr_ep(Dbg_MCState *state, Dbg_Environment const *context,
                  char const *expr, char **exprend, int flags, Dbg_Value *val);

/* Both Dbg_ValueOfVar and Dbg_EvalExpr mostly deliver a value still containing
   an indirection (since it may be wanted as the lhs of an assignment)
 */

void Dbg_RealLocation(Dbg_MCState *state, Dbg_Value *val);
/* If val describes a register, this may really be a register, or a place on
   the stack where the register's value is saved. In the latter case, val
   is altered to describe the save place. (In all others, it remains
   unchanged).
 */

Dbg_Error Dbg_DereferenceValue(Dbg_MCState *state, const Dbg_Value *value, Dbg_Constant *c);
/* This fails if <value> describes a structure or array, returning
   Dbg_Err_TypeNotSimple
 */

typedef struct Dbg_Expr Dbg_Expr;
/* The result of parsing an expression in an environment: its structure is not
   revealed.  (Clients may wish to parse just once an expression which may be
   evaluated often).  In support of which, the following two functions partition
   the work of Dbg_EvalExpr().
 */

#define Dbg_exfl_heap 1    /* allocate Expr on the heap (FreeExpr must then be
                              called to discard it).  Otherwise, it goes in a
                              place overwritten by the next call to ParseExpr
                              or EvalExpr
                            */
#define Dbg_exfl_needassign 2
#define Dbg_exfl_lowlevel   4

int Dbg_SetInputRadix(Dbg_MCState *state, int radix);
char *Dbg_SetDefaultIntFormat(Dbg_MCState *state, char *format);

Dbg_Error Dbg_ParseExpr(
    Dbg_MCState *state, Dbg_Environment const *env, char *string,
    char **end, Dbg_Expr **res, int flags);
/* Just parse the argument string, returning a pointer to a parsed expression
   and a pointer to the first non-white space character in the input string
   which is not part of the parsed expression. (If macro expansion has taken
   place, the returned pointer will not be into the argument string at all,
   rather into the expanded version of it).
 */

Dbg_Error Dbg_ParseExprCheckEnd(
    Dbg_MCState *state, Dbg_Environment const *env, char *string,
    Dbg_Expr **res, int flags);
/* As Dbg_ParseExpr, but the parsed expression is required completely to fill
   the argument string (apart possibly for trailing whitespace), and an error
   is returned if it does not.
 */

Dbg_Error Dbg_ParsedExprToValue(
    Dbg_MCState *state, const Dbg_Environment *env, Dbg_Expr *expr, Dbg_Value *v);

Dbg_Error Dbg_ReadDecl(
    Dbg_MCState *state, Dbg_Environment const *env, char *string,
    Dbg_TypeSpec *p, char **varp, int flags);
/* Read a variable declaration, returing a description of the type of the
   variable to p, and a pointer to its name to varp.
 */

bool Dbg_IsCastToArrayType(Dbg_MCState *state, Dbg_Expr *expr);

void Dbg_FreeExpr(Dbg_Expr *expr);

Dbg_Error Dbg_CopyType(Dbg_TypeSpec *tdest, Dbg_TypeSpec const *tsource);
Dbg_Error Dbg_FreeCopiedType(Dbg_TypeSpec *ts);

Dbg_Error Dbg_TypeOfExpr(Dbg_MCState *state, Dbg_Expr *tree, Dbg_TypeSpec *restype);

Dbg_Error Dbg_ExprToVar(const Dbg_Expr *expr, Dbg_DeclSpec *var, Dbg_Environment *env);

Dbg_Error Dbg_Assign(Dbg_MCState *state, const Dbg_Value *lv, const Dbg_Value *rv);

typedef enum Dbg_TypeSort {
  ts_simple,
  ts_union,
  ts_struct,
  ts_array
} Dbg_TypeSort;

Dbg_TypeSort Dbg_TypeSortOfValue(Dbg_MCState *state, const Dbg_Value *val, int *fieldcount);

Dbg_Error Dbg_TypeToChars(const Dbg_TypeSpec *var, Dbg_BufDesc *buf);

Dbg_Error Dbg_TypeSize(Dbg_MCState *state, const Dbg_TypeSpec *type, unsigned32 *res);

typedef int Dbg_ValToChars_cb(Dbg_MCState *state, Dbg_Value *subval, const char *fieldname,
                          Dbg_BufDesc *buf, void *arg);

Dbg_Error Dbg_ValToChars(Dbg_MCState *state, Dbg_Value *val, int base,
                 Dbg_ValToChars_cb *cb, void *arg,
                 const char *form, Dbg_BufDesc *buf);
/*
   <base> is used for (any size) integer values.
   If <val> is of an array or structure type, <cb> is called for each element,
   with <arg> as its last parameter, and <subbuf> describing the space remaining
   in <buf>.  If <cb> returns 0, conversion ceases.
 */

Dbg_Error Dbg_NthElement(
    Dbg_MCState *state,
    const Dbg_Value *val, unsigned32 n, char **fieldname, Dbg_Value *subval);

typedef Dbg_Error Dbg_HistoryProc(void *, int, Dbg_Value *);

Dbg_Error Dbg_RegisterHistoryProc(Dbg_MCState *state, Dbg_HistoryProc *p, void *arg);

typedef enum {
  ls_cpu,
  ls_store,
  ls_copro,
  ls_local,
  ls_filtered
} Dbg_LocSort;

typedef struct {
  Dbg_LocSort sort;
  union {
    struct { ARMaddress addr, size; } store;
    struct { int modemask; int r; } cpu;
    struct { int no; int r; } cp;
    void *localp;
    Dbg_AccessFnRec f;
  } loc;
} Dbg_Loc;

typedef Dbg_Error Dbg_ObjectWriteProc(Dbg_MCState *state, Dbg_Loc const *loc);
Dbg_Error Dbg_OnObjectWrite(Dbg_MCState *state, Dbg_ObjectWriteProc *p);
/* Register function to be called back whenever the toolbox has written to any
 * object accessible by the debuggee (or to local variables belonging to a
 * toolbox client). The write has already been done.
 * (To allow multiple toolbox clients to coexist).
 */

Dbg_Error Dbg_ObjectWritten(Dbg_MCState *state, Dbg_Loc const *loc);

/*--------------------------------------------------------------------------*/

/* Control of target program execution.
   Currently, only synchronous operation is provided.
   Execution could possibly be asynchronous where the target is a seperate
   processor, but is necessarily synchronous if the target is Armulator.
   Unfortunately, this may require modification to the RDI implementation
   if multitasking is required but the the host system provides it only
   cooperatively, or if there is no system-provided way to generate SIGINT.
 */

Dbg_Error Dbg_SetCommandline(Dbg_MCState *state, const char *args);
/* Set the argument string to the concatenation of the name of the most
   recently loaded image and args.
 */

typedef enum Dbg_ProgramState {
    ps_notstarted,
    /* Normal ways of stopping */
    ps_atbreak, ps_atwatch, ps_stepdone,
    ps_interrupted,
    ps_stopped,
    /* abnormal (but unsurprising) ways of stopping */
    ps_lostwatch,
    ps_branchthrough0, ps_undef, ps_caughtswi, ps_prefetch,
    ps_abort, ps_addrexcept, ps_caughtirq, ps_caughtfiq,
    ps_error,
    /* only as a return value from Call() */
    ps_callfailed, ps_callreturned,
    /* internal inconsistencies */
    ps_broken,                  /* target has "broken" */
    ps_unknownbreak,
    ps_unknown
} Dbg_ProgramState;

int Dbg_IsCallLink(Dbg_MCState *state, ARMaddress pc);

typedef struct {
    Dbg_FPRegVal fpres;
    ARMword intres;
} Dbg_CallResults;

Dbg_CallResults *Dbg_GetCallResults(Dbg_MCState *state);

#define Dbg_S_STATEMENTS 0
#define Dbg_S_INSTRUCTIONS 1
#define Dbg_S_STEPINTOPROCS 2

Dbg_Error Dbg_Step(Dbg_MCState *state, int32 stepcount, int stepby, Dbg_ProgramState *status);
/*  <stepby> is a combination of the Dbg_S_... values above */

Dbg_Error Dbg_StepOut(Dbg_MCState *state, Dbg_ProgramState *status);

bool Dbg_CanGo(Dbg_MCState *state);

bool Dbg_IsExecuting(Dbg_MCState *state);

Dbg_Error Dbg_Go(Dbg_MCState *state, Dbg_ProgramState *status);

Dbg_Error Dbg_Stop(Dbg_MCState *state);
/* Asynchronous Stop request, for call from SIGINT handler.  On return to the
   caller, the call of Dbg_Go, Dbg_Step or Dbg_Call which started execution
   should return ps_interrupted.
 */

typedef void Dbg_ExecuteProc(Dbg_MCState *state, Dbg_ProgramState status);
Dbg_Error Dbg_OnExecute(Dbg_MCState *, Dbg_ExecuteProc *);
/* Register function to be called back whenever execution stops.
 * (To allow multiple toolbox clients to coexist).
 */

Dbg_Error Dbg_SetReturn(Dbg_MCState *state,
                const Dbg_Environment *context, const Dbg_Value *value);
/* Prepare continuation by returning <value> from the function activation
   described by <context>.  (Dbg_Go() or Dbg_Step() actually perform the
   continuation).
 */

Dbg_Error Dbg_SetExecution(Dbg_MCState *state, Dbg_Environment *context);
/* Set the pc in a high-level fashion */

Dbg_Error Dbg_ProgramStateToChars(Dbg_MCState *state, Dbg_ProgramState event, Dbg_BufDesc *buf);
/* This is guaranteed to give a completely accurate description of <event> if
   this was the value returned by the most recent call of Dbg_Go, Dbg_Step,
   or Dbg_Call.
 */

/*--------------------------------------------------------------------------*/

Dbg_Error Dbg_CurrentEnvironment(Dbg_MCState *state, Dbg_Environment *context);

Dbg_Error Dbg_PrevFrame(Dbg_MCState *state, Dbg_Environment *context);
/* towards the base of the stack */

Dbg_Error Dbg_NextFrame(Dbg_MCState *state, Dbg_Environment *context);
/* away from the base of the stack */

typedef struct Dbg_AnyPos {
    enum { pos_source, pos_ll, pos_none } postype;
    ARMaddress pc;
    union {
        Dbg_ProcPos source;
        Dbg_LLPos ll;
        ARMaddress none;
    } pos;
} Dbg_AnyPos;

Dbg_Error Dbg_EnvironmentToPos(Dbg_MCState *state, const Dbg_Environment *context, Dbg_AnyPos *pos);
/* <pos> is set to a Dbg_ProcPos if these is one corresponding to <context>
   else a Dbg_LLPos if there is one.
 */

/*--------------------------------------------------------------------------*/

/* Source file management.
   Pretty vestigial.  Handles source path (per loaded image),
   and translates from line-number (as given in debugger tables) to character
   position (as required to access files)
 */

Dbg_Error Dbg_ClearPaths(Dbg_MCState *state, Dbg_SymTable *st);
Dbg_Error Dbg_AddPath(Dbg_MCState *state, Dbg_SymTable *st, const char *path);
Dbg_Error Dbg_DeletePath(Dbg_MCState *state, Dbg_SymTable *st, const char *path);

typedef enum {
  Dbg_PathsCleared,
  Dbg_PathAdded,
  Dbg_PathDeleted
} Dbg_PathAlteration;

typedef void Dbg_PathAlteredProc(
    Dbg_MCState *state, Dbg_SymTable *st, char const *path,
    Dbg_PathAlteration sort);

Dbg_Error Dbg_OnPathAlteration(Dbg_MCState *state, Dbg_PathAlteredProc *p);
/* Register function to be called back whenever one of the source path
 * modification functions above is called. (To allow multiple toolbox
 * clients to coexist).
 */

typedef struct Dbg_FileRec Dbg_FileRec;
typedef struct {
  unsigned32 linecount;
  Dbg_FileRec *handle;
  char *fullname;
} Dbg_FileDetails;

Dbg_Error Dbg_GetFileDetails(
    Dbg_MCState *state, const Dbg_File *fname, Dbg_FileDetails *res);
Dbg_Error Dbg_FinishedWithFile(Dbg_MCState *state, Dbg_FileRec *handle);

Dbg_Error Dbg_GetFileDetails_fr(
    Dbg_MCState *state, Dbg_FileRec *handle, Dbg_FileDetails *res);
/* Refresh details about the file associated with <handle> (in particular,
 * its linecount).
 */

Dbg_Error Dbg_FileLineLength(
    Dbg_MCState *state, Dbg_FileRec *handle, int32 lineno, int32 *len);
/* Return to <len> the length of line <lineno> of the file associated with
 * <handle> (without necessarily reading from the file).
 */

Dbg_Error Dbg_GetFileLine_fr(
    Dbg_MCState *state, Dbg_FileRec *handle, int32 lineno, Dbg_BufDesc *buf);
/* Return to <buf> the contents of line <lineno> of the file associated with
 * <handle> (including its terminating newline).
 */

Dbg_Error Dbg_StartFileAccess(Dbg_MCState *state, Dbg_FileRec *handle);
Dbg_Error Dbg_EndFileAccess(Dbg_MCState *state, Dbg_FileRec *handle);
/* These two calls bracket a sequence of calls to GetFileLine. Between the
 * calls, the toolbox is permitted to retain state allowing more rapid
 * access to text on the file associated with <handle>.
 */

Dbg_Error Dbg_ControlSourceFileAccess(
    Dbg_MCState *state, uint32 cachesize, bool closefiles);
/* Control details of how the toolbox manages source files.
 *   If <cachesize> is non-zero, the text from the most recently accessed
 *     source files (of total size not to exceed <cachesize>) is saved in
 *     store on first access to the file; subsequent access to the text of
 *     the file uses this copy.
 *   If <closefiles> is true, no stream is left attached to uncached source
 *     files after Dbg_EndFileAccess has been closed. Otherwise, the toolbox
 *     may retain such streams, in order to improve access.
 */

/*--------------------------------------------------------------------------*/

/* disassembly */

/*
 ? More exact control is wanted here, but that requires a more complicated
 ? disass callback interface.
 */

typedef const char *Dbg_SWI_Decode(Dbg_MCState *state, ARMword swino);

Dbg_Error Dbg_InstructionAt(Dbg_MCState *state, ARMaddress addr,
                    int isize, ARMhword *inst, Dbg_SymTable *st,
                    Dbg_SWI_Decode *swi_name, Dbg_BufDesc *buf, int *length);
/* <isize> describes the form of disassembly wanted: 2 for 16-bit, 4 for 32-bit,
 * 0 for 16- or 32-bit depending whether addr addresses 16- or 32-bit code.
 * <inst> is a pointer to a pair of halfwords *in target byte order*
 * Possibly only the first halfword will be consumed: the number of bytes used
 * is returned via <length>.
 */

/*--------------------------------------------------------------------------*/

int Dbg_RDIOpen(Dbg_MCState *state, unsigned type);
int Dbg_RDIInfo(Dbg_MCState *state, unsigned type, ARMword *arg1, ARMword *arg2);

/*--------------------------------------------------------------------------*/

typedef enum {
    Dbg_Point_Toolbox,
    Dbg_Point_RDI_Unknown,
    Dbg_Point_RDI_SW,
    Dbg_Point_RDI_HW
} Dbg_PointType;

/* breakpoint management
   Associated with a breakpoint there may be any of
     a count
     an expression
     a function
   the breakpoint is activated if
        the expression evaluates to a non-zero value (or fails to evaluate).
     && decrementing the count reaches zero (the count is then reset to its
        initial value).
     && the function, called with the breakpoint address as argument, returns
        a non-zero value.
?  (The order here may be open to debate.  Note that the first two are in
    the opposite order in armsd, but I think this order more rational)
 */

typedef enum Dbg_BreakPosType {
    bt_procpos,
    bt_procexit,
    bt_address
} Dbg_BreakPosType;

typedef union {
      Dbg_ProcPos procpos;
      Dbg_ProcDesc procexit;
      ARMaddress address;
} Dbg_BreakPosPos;

typedef struct Dbg_BreakPos {
    Dbg_BreakPosType sort;
    Dbg_BreakPosPos loc;
} Dbg_BreakPos;

typedef int Dbg_BPProc(Dbg_MCState *state, void *BPArg, Dbg_BreakPos *where);

typedef struct Dbg_BreakStatus {
    int index;
    int initcount, countnow;
    Dbg_BreakPos where;
    char *expr;
    Dbg_BPProc *p; void *p_arg;
    int incomplete;
    Dbg_PointType type;
    ARMword hwresource;
} Dbg_BreakStatus;

Dbg_Error Dbg_StringToBreakPos(
    Dbg_MCState *state, Dbg_Environment *env, char const *str, size_t len,
    Dbg_BreakPos *bpos, char *b);

Dbg_Error Dbg_SetBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where,
                    int count,
                    const char *expr,
                    Dbg_BPProc *p, void *arg);
Dbg_Error Dbg_SetBreakPoint16(Dbg_MCState *state, Dbg_BreakPos *where,
                    int count,
                    const char *expr,
                    Dbg_BPProc *p, void *arg);
Dbg_Error Dbg_SetBreakPointNaturalSize(Dbg_MCState *state, Dbg_BreakPos *where,
                    int count,
                    const char *expr,
                    Dbg_BPProc *p, void *arg);
/* Setting a breakpoint at the same address as a previous breakpoint
   completely removes the previous one.
 */

Dbg_Error Dbg_DeleteBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);

Dbg_Error Dbg_SuspendBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);
/* Temporarily remove the break point (until Reinstated) but leave intact
   its associated expr, the value its count has reached, etc.
?  The debugger toolbox itself wants this, but I'm not sure what use a client
   could have for it.  Ditto Reinstate...
 */

Dbg_Error Dbg_ReinstateBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);
/* Undo the effect of Dbg_SuspendBreakPoint
 */

Dbg_Error Dbg_DeleteAllBreakPoints(Dbg_MCState *state);

Dbg_Error Dbg_SuspendAllBreakPoints(Dbg_MCState *state);

Dbg_Error Dbg_ReinstateAllBreakPoints(Dbg_MCState *state);

typedef Dbg_Error Dbg_BPEnumProc(Dbg_MCState *state, Dbg_BreakStatus *status, void *arg);

Dbg_Error Dbg_EnumerateBreakPoints(Dbg_MCState *state, Dbg_BPEnumProc *p, void *arg);

Dbg_Error Dbg_BreakPointStatus(Dbg_MCState *state,
                       const Dbg_BreakPos *where, Dbg_BreakStatus *status);

typedef void Dbg_BreakAlteredProc(Dbg_MCState *state, ARMaddress addr, bool set);
Dbg_Error Dbg_OnBreak(Dbg_MCState *state, Dbg_BreakAlteredProc *p);
/* Register function to be called back whenever a breakpoint is set or
 * cleared. (To allow multiple toolbox clients to coexist).
 */

bool Dbg_StoppedAtBreakPoint(Dbg_MCState *state, const Dbg_BreakPos *where);
/* Called after execution which resulted in ps_atbreak, to find out whether
   the specified breakpoint was hit (could be >1, eg. exit break and another
   high-level breakpoint at the same position).
   Returns NO if specified breakpoint not found, or execution didn't stop
   with ps_atbreak status.
 */

/*--------------------------------------------------------------------------*/

typedef struct {
  Dbg_Value val;
  char *name;
} Dbg_WatchPos;

typedef int Dbg_WPProc(Dbg_MCState *state, void *WPArg, Dbg_WatchPos *where);

typedef struct Dbg_WPStatus {
    int index;
    int initcount, countnow;
    Dbg_WatchPos what, target;
    char *expr;
    Dbg_WPProc *p; void *p_arg;
    Dbg_PointType type;
    ARMword hwresource;
    int skip;
} Dbg_WPStatus;

Dbg_Error Dbg_SetWatchPoint(
    Dbg_MCState *state, Dbg_Environment *context, char const *watchee,
    char const *target,
    int count,
    char const *expr,
    Dbg_WPProc *p, void *arg);

/* Cause a watchpoint event if the value of <watchee> changes to the value of
   <target> (or changes at all if <target> is NULL).  <watchee> should
   evaluate either to an L-value (when the size of the object being watched is
   determined by its type) or to an integer constant (when the word with this
   address is watched).
 */

Dbg_Error Dbg_DeleteWatchPoint(Dbg_MCState *state, Dbg_Environment *context, char const *watchee);


Dbg_Error Dbg_SetWatchPoint_V(
    Dbg_MCState *state,
    char const *name, Dbg_Value const *val, char const *tname, Dbg_Value const *tval,
    int count,
    char const *expr,
    Dbg_WPProc *p, void *arg);

Dbg_Error Dbg_DeleteWatchPoint_V(Dbg_MCState *state, Dbg_Value const *val);


Dbg_Error Dbg_DeleteAllWatchPoints(Dbg_MCState *state);

typedef Dbg_Error Dbg_WPEnumProc(Dbg_MCState *state, Dbg_WPStatus const *watchee, void *arg);

Dbg_Error Dbg_EnumerateWatchPoints(Dbg_MCState *state, Dbg_WPEnumProc *p, void *arg);

Dbg_Error Dbg_WatchPointStatus(Dbg_MCState *state,
                       Dbg_WatchPos const *where, Dbg_WPStatus *status);

typedef void Dbg_WPRemovedProc(void *arg, Dbg_WPStatus const *wp);
Dbg_Error Dbg_RegisterWPRemovalProc(Dbg_MCState *state, Dbg_WPRemovedProc *p, void *arg);
/* When a watchpoint goes out of scope it is removed by the toolbox, and the
   function registered here gets called back to adjust its view
 */

typedef void Dbg_WatchAlteredProc(Dbg_MCState *state, Dbg_Value const *where, bool set);
Dbg_Error Dbg_OnWatch(Dbg_MCState *state, Dbg_WatchAlteredProc *p);
/* Register function to be called back whenever a watchpoint is set or
 * cleared. (To allow multiple toolbox clients to coexist).
 */

/*--------------------------------------------------------------------------*/

Dbg_Error Dbg_ProfileLoad(Dbg_MCState *state);

Dbg_Error Dbg_ProfileStart(Dbg_MCState *state, ARMword interval);
Dbg_Error Dbg_ProfileStop(Dbg_MCState *state);

Dbg_Error Dbg_ProfileClear(Dbg_MCState *state);

Dbg_Error Dbg_WriteProfile(Dbg_MCState *state, char const *filename,
                           char const *toolid, char const *arg);

/*--------------------------------------------------------------------------*/

Dbg_Error Dbg_ConnectChannel_ToHost(Dbg_MCState *state, RDICCProc_ToHost *p, void *arg);
Dbg_Error Dbg_ConnectChannel_FromHost(Dbg_MCState *state, RDICCProc_FromHost *p, void *arg);

/*--------------------------------------------------------------------------*/

/* Configuration data management */

Dbg_Error Dbg_LoadConfigData(Dbg_MCState *state, char const *filename);

Dbg_Error Dbg_SelectConfig(
    Dbg_MCState *state,
    RDI_ConfigAspect aspect, char const *name, RDI_ConfigMatchType matchtype,
    unsigned versionreq, unsigned *versionp);

Dbg_Error Dbg_ParseConfigVersion(
    char const *s, RDI_ConfigMatchType *matchp, unsigned *versionp);

typedef Dbg_Error Dbg_ConfigEnumProc(Dbg_MCState *state, RDI_ConfigDesc const *desc, void *arg);

Dbg_Error Dbg_EnumerateConfigs(Dbg_MCState *state, Dbg_ConfigEnumProc *p, void *arg);

/*--------------------------------------------------------------------------*/

/* Angel OS support */

Dbg_Error Dbg_CreateTask(Dbg_MCState **statep, Dbg_MCState *parent, bool inherit);
/* This is called when a task is to be debugged which has not been debugged
   before - ie. there is no existing Dbg_MCState for this task. It
   initialises a new Dbg_MCState and returns a pointer to it.
   <parent> is any valid previously-created MCCState. If <inherit> is TRUE,
   the new MCState inherits certain features from it (eg. symbols).
   Otherwise, only features which are the same across all tasks are inherited,
   (eg. global breakpoints).
 */

Dbg_Error Dbg_DeleteTask(Dbg_MCState *state);
/* This is called when a task dies, and frees up everything which relates to that
   task which is controlled by armdbg.
 */

Dbg_Error Dbg_DetachTask(Dbg_MCState *state);

Dbg_Error Dbg_AttachTask(Dbg_MCState *state);
/* These are called to request a switch of the current task.  First
   Dbg_DetachTask should be called with the state of the old task.
   Dbg_DetachTask will ensure that any cached state held by armdbg for
   the old task is immediately written out to the target.

   After Dbg_DetachTask is called and before Dbg_AttachTask is called
   the OS channel manager should tell the target that any future
   requests from the debugger will be fore the new task.

   If the new task does not have an armdbg state structure
   already, then Dbg_CreateTask should be called to create one (see
   above).  Then Dbg_AttachTask is called to tell armdbg to treat the
   new armdbg state as the current task.
 */

typedef Dbg_Error Dbg_TaskSwitchProc(void *arg, Dbg_MCState *newstate);

Dbg_Error Dbg_OnTaskSwitch(Dbg_MCState *state, Dbg_TaskSwitchProc *fn, void *arg);
/* The front end may register a callback which gets called by armdbg whenever
   Dbg_AttachTask is called.  This callback tells the front end the new current
   Dbg_MCState it should use to call armdbg.
   [Note that this is only useful if there is one front end shared between all
    tasks rather than one front end per task]
   The value of <arg> passed to Dbg_OnTaskSwitch is passed to <fn>
   when it is called.
 */

typedef Dbg_Error Dbg_RestartProc(
    void *arg, Dbg_MCState *curstate, Dbg_MCState **newstate);

Dbg_Error Dbg_OnRestart(Dbg_MCState *state, Dbg_RestartProc *fn, void *arg);
/* This is used by the OS channels layer to register a callback which
   will be made by the debugger toolbox early in the process of resuming
   execution.

   This callback must determine which task will be resumed when the target
   restarts execution.  If this is not already the current task then it must
   call Dbg_DetachTask and Dbg_AttachTask as decribed above to switch to the
   task about to be resumed and return the state for the new task in
   <newstate>.

   This will ensure that armdbg updates the correct task on execution as well
   as ensuring that stepping over a breakpointed instruction on restarting
   happens correctly.

   The value of <arg> passed to Dbg_OnRestart is passed to <fn>
   when it is called.
 */


#ifdef __cplusplus
}
#endif

#endif

/* End of armdbg.h */