1/*
2 * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
3 *
4 * This software may be freely used, copied, modified, and distributed
5 * provided that the above copyright notice is preserved in all copies of the
6 * software.
7 */
8
9/*
10 * ARM symbolic debugger toolbox interface
11 */
12
13/*
14 * RCS $Revision: 1.2 $
15 * Checkin $Date: 1998/01/08 11:11:32 $
16 */
17
18/* Minor points of uncertainty are indicated by a question mark in the
19   LH margin.
20
21   Wherever an interface is required to iterate over things of some class,
22   I prefer something of the form  EnumerateXXs(..., XXProc *p, void *arg)
23   which results in a call of p(xx, arg) for each xx, rather than something
24   of the form
25     for (xxh = StartIterationOverXXs(); (xx = Next(xxh)) != 0; ) { ... }
26     EndIterationOverXXs(xxh);
27   Others may disagree.
28   (Each XXProc returns an Error value: if this is not Err_OK, iteration
29   stops immediately and the EnumerateXXs function returns that value).
30
31   ptrace has been retired as of insufficient utility.  If such fuctionality is
32   required, it can be constructed using breakpoints.
33
34   The file form of all name fields in debug areas is in-line, with a length
35   byte and no terminator.  The debugger toolbox makes an in-store translation,
36   where the strings are out of line (the namep variant in asdfmt.h) and have a
37   terminating zero byte: the pointer is to the first character of the string
38   with the length byte at ...->n.namep[-1].
39 */
40
41#ifndef armdbg__h
42#define armdbg__h
43
44#include <stddef.h>
45
46#include "host.h"
47#include "msg.h"
48
49typedef unsigned32 ARMaddress;
50typedef unsigned32 ARMword;
51typedef unsigned16 ARMhword;
52
53#include "dbg_conf.h"
54#include "dbg_rdi.h"
55
56#ifdef __cplusplus
57extern "C"
58{
59#endif
60
61typedef unsigned char Dbg_Byte;
62
63typedef int Dbg_Error;
64
65typedef struct Dbg_MCState Dbg_MCState;
66/* A representation of the state of the target.  The structure is not revealed.
67   A pointer to one of these is returned by Dbg_Initialise(), is passed to all
68   toolbox calls which refer to the state of the target, and is discarded
69   by Dbg_Finalise().
70   Nothing in the toolbox itself precludes there being multiple targets, each
71   with its own state.
72 */
73
74/* Most toolbox interfaces return an error status.  Only a few of the status
75   values are expected to be interesting to clients and defined here; the
76   rest are private (but a textual form can be produced by ErrorToChars()).
77 */
78
79#define Error_OK 0
80
81/* Partitioning of the error code space: errors below Dbg_Error_Base are RDI
82   errors (as defined in dbg_rdi.h). Codes above Dbg_Error_Limit are
83   available to clients, who may impose some further structure.
84 */
85#define Dbg_Error_Base 0x1000
86#define Dbg_Error_Limit 0x2000
87
88#define DbgError(n) ((Dbg_Error)(Dbg_Error_Base+(n)))
89
90#define Dbg_Err_OK Error_OK
91#define Dbg_Err_Interrupted             DbgError(1)
92#define Dbg_Err_Overflow                DbgError(2)
93#define Dbg_Err_FileNotFound            DbgError(3)
94#define Dbg_Err_ActivationNotPresent    DbgError(4)
95#define Dbg_Err_OutOfHeap               DbgError(5)
96#define Dbg_Err_TypeNotSimple           DbgError(6)
97#define Dbg_Err_BufferFull              DbgError(7)
98#define Dbg_Err_AtStackBase             DbgError(8)
99#define Dbg_Err_AtStackTop              DbgError(9)
100#define Dbg_Err_DbgTableFormat          DbgError(10)
101#define Dbg_Err_NotVariable             DbgError(11)
102#define Dbg_Err_NoSuchBreakPoint        DbgError(12)
103#define Dbg_Err_NoSuchWatchPoint        DbgError(13)
104#define Dbg_Err_FileLineNotFound        DbgError(14)
105#define Dbg_Err_DbgTableVersion         DbgError(15)
106#define Dbg_Err_NoSuchPath              DbgError(16)
107#define Dbg_Err_StateChanged            DbgError(17)
108#define Dbg_Err_SoftInitialiseError     DbgError(18)
109#define Dbg_Err_CoProRegNotWritable     DbgError(19)
110#define Dbg_Err_NotInHistory            DbgError(20)
111#define Dbg_Err_ContextSyntax           DbgError(21)
112#define Dbg_Err_ContextNoLine           DbgError(22)
113#define Dbg_Err_ContextTwoLines         DbgError(23)
114#define Dbg_Err_VarReadOnly             DbgError(24)
115#define Dbg_Err_FileNewerThanImage      DbgError(25)
116#define Dbg_Err_NotFound                DbgError(26)
117
118   /* functions which evaluate expressions may return this value, to indicate
119      that execution became suspended within a function called in the debugee */
120
121/* Functions returning characters take a BufDesc argument, with fields buffer
122   and bufsize being input arguments describing the buffer to be filled, and
123   filled being set on return to the number of bytes written to the buffer
124   (omitting the terminating 0).
125 */
126
127typedef struct Dbg_BufDesc Dbg_BufDesc;
128
129typedef void Dbg_BufferFullProc(Dbg_BufDesc *bd);
130
131struct Dbg_BufDesc {
132    char *buffer;
133    size_t size,
134           filled;
135    Dbg_BufferFullProc *p;
136    void *arg;
137};
138
139#define Dbg_InitBufDesc(bd, buf, bytes) \
140    ((bd).buffer = (buf), (bd).size = (bytes), (bd).filled = 0,\
141     (bd).p = NULL, (bd).arg = NULL)
142
143#define Dbg_InitBufDesc_P(bd, buf, bytes, fn, a) \
144    ((bd).buffer = (buf), (bd).size = (bytes), (bd).filled = 0,\
145     (bd).p = (fn), (bd).arg = (a))
146
147Dbg_Error Dbg_StringToBuf(Dbg_BufDesc *buf, char const *s);
148Dbg_Error Dbg_BufPrintf(Dbg_BufDesc *buf, char const *form, ...);
149#ifdef NLS
150Dbg_Error Dbg_MsgToBuf(Dbg_BufDesc *buf, msg_t t);
151Dbg_Error Dbg_BufMsgPrintf(Dbg_BufDesc *buf, msg_t form, ...);
152#else
153#define Dbg_MsgToBuf Dbg_StringToBuf
154#define Dbg_BufMsgPrintf Dbg_BufPrintf
155#endif
156Dbg_Error Dbg_CharToBuf(Dbg_BufDesc *buf, int ch);
157
158int Dbg_CIStrCmp(char const *s1, char const *s2);
159/* Case-independent string comparison, interface as for strcmp */
160
161int Dbg_CIStrnCmp(char const *s1, char const *s2, size_t n);
162/* Case-independent string comparison, interface as for strncmp */
163
164void Dbg_ErrorToChars(Dbg_MCState *state, Dbg_Error err, Dbg_BufDesc *buf);
165
166typedef int Dbg_RDIResetCheckProc(int);
167/* Type of a function to be called after each RDI operation performed by the
168   toolbox, with the status from the operation as argument.  The value returned
169   is treated as the status.  (The intent is to allow the toolbox's client to
170   take special action to handle RDIDbg_Error_Reset).
171 */
172
173typedef struct Dbg_CoProDesc Dbg_CoProDesc;
174
175typedef Dbg_Error Dbg_CoProFoundProc(Dbg_MCState *state, int cpno, Dbg_CoProDesc const *cpd);
176/* Type of a function to be called when the shape of a coprocessor is discovered
177   by enquiry of the target or agent (via RequestCoProDesc)
178 */
179
180typedef struct RDIProcVec RDIProcVec;
181
182Dbg_Error Dbg_RequestReset(Dbg_MCState *);
183
184Dbg_Error Dbg_Initialise(
185    Dbg_ConfigBlock *config, Dbg_HostosInterface const *i,
186    Dbg_RDIResetCheckProc *checkreset, Dbg_CoProFoundProc *coprofound,
187    RDIProcVec const *rdi, Dbg_MCState **statep);
188/* values in config are updated if they call for default values */
189
190void Dbg_Finalise(Dbg_MCState *state, bool targetdead);
191
192typedef struct {
193    char name[16];
194    RDI_MemDescr md;
195    RDI_MemAccessStats a;
196} Dbg_MemStats;
197
198/*--------------------------------------------------------------------------*/
199
200/* Symbol table management.
201   The structure of a Dbg_SymTable is not revealed.  It is created by
202   Dbg_ReadSymbols() or by Dbg_LoadFile(), and associated with the argument
203   Dbg_MCState.
204   Many symbol tables may be concurrently active.
205   A Dbg_SymTable is removed either explicitly (by call to Dbg_DeleteSymbols)
206   or implicitly when a symbol table for an overlapping address range is read.
207
208   There is a pre-defined symbol table containing entries for ARM registers,
209   co-processor registers and the like.
210 */
211
212typedef struct Dbg_SymTable Dbg_SymTable;
213
214typedef struct Dbg_ImageFragmentDesc {
215    ARMaddress base, limit;
216} Dbg_ImageFragmentDesc;
217
218typedef enum {
219    Dbg_Lang_None,
220    Dbg_Lang_C,
221    Dbg_Lang_Pascal,
222    Dbg_Lang_Fortran,
223    Dbg_Lang_Asm,
224    Dbg_Lang_Cpp
225} Dbg_Lang;
226
227typedef struct Dbg_ImageDesc {
228    Dbg_Lang lang;
229    int executable;
230    ARMaddress robase, rolimit, rwbase, rwlimit;
231    int nfrags;
232    Dbg_ImageFragmentDesc *fragments;
233    char *name;
234} Dbg_ImageDesc;
235
236Dbg_ImageDesc *Dbg_ImageAreas(Dbg_SymTable *st);
237
238Dbg_SymTable *Dbg_LastImage(Dbg_MCState *state);
239
240Dbg_SymTable *Dbg_NewSymTable(Dbg_MCState *state, const char *name);
241
242Dbg_Error Dbg_ReadSymbols(Dbg_MCState *state, const char *filename, Dbg_SymTable **st);
243/* Just read the symbols from the named image.  <st> is set to the allocated
244   symbol table.
245?  Maybe we could usefully allow other formats than AIF images to describe
246   the symbols (eg) of shared libraries
247 */
248
249typedef struct Dbg_SymInfo {
250    int isize;
251    ARMaddress addr;
252    char *name;
253} Dbg_SymInfo;
254
255Dbg_SymInfo *Dbg_AsmSym(Dbg_SymTable *st, ARMaddress addr);
256int32 Dbg_AsmAddr(Dbg_SymTable *st, int32 line);
257int32 Dbg_AsmLine(Dbg_SymTable *st, ARMaddress addr);
258int32 Dbg_AsmLinesInRange(Dbg_SymTable *st, ARMaddress start, ARMaddress end);
259
260Dbg_Error Dbg_LoadFile(Dbg_MCState *state, const char *filename, Dbg_SymTable **st);
261/* load the image into target memory, and read its symbols.  <st> is set to
262   the allocated symbol table.
263   A null filename reloads the most recently loaded file (and rereads its
264   symbols).
265   Loading an image leaves breakpoints unchanged.  If a client wishes
266   otherwise, it must remove the breakpoints explicitly.
267*/
268
269Dbg_Error Dbg_CallGLoadFile(Dbg_MCState *state, const char *filename, Dbg_SymTable **st);
270
271typedef void Dbg_ImageLoadProc(Dbg_MCState *, Dbg_SymTable *);
272Dbg_Error Dbg_OnImageLoad(Dbg_MCState *, Dbg_ImageLoadProc *);
273/* Register function to be called back whenever an image is loaded, or symbols
274 * for an image read. (To allow multiple toolbox clients to coexist).
275 */
276
277Dbg_Error Dbg_LoadAgent(Dbg_MCState *state, const char *filename);
278/* Load a debug agent, and start it.
279   Symbols in the image for the agent are ignored.
280*/
281
282Dbg_Error Dbg_RelocateSymbols(Dbg_SymTable *st, ARMaddress reloc);
283/* add <reloc> to the value of all symbols in <st> describing absolute memory
284   locations.  The intent is to allow the symbols in a load-time relocating
285   image (for example) to be useful.
286 */
287
288Dbg_Error Dbg_DeleteSymbols(Dbg_MCState *state, Dbg_SymTable **st);
289
290typedef enum Dbg_LLSymType {
291    llst_code,
292    llst_code16,
293    llst_data,
294    llst_const,
295    llst_unknown,
296    llst_max
297} Dbg_LLSymType;
298/* Since AIF images contain no type information for low-level symbols, this
299   classification is only a guess, and some symbols describing constants will
300   incorrectly be described as code or data.
301 */
302
303typedef Dbg_Error Dbg_SymProc(
304    Dbg_MCState *state,
305    const char *symbol, Dbg_LLSymType symtype, ARMaddress value,
306    void *arg);
307
308Dbg_Error Dbg_EnumerateLowLevelSymbols(
309    Dbg_MCState *state, const char *match, Dbg_SymProc *p,
310    void *arg);
311/* Call  p(name, value)  for each low level symbol in the tables of <state>
312   whose name matches the regular expression <match> (a NULL <match> matches
313   any name).  Symbols are enumerated in no particular order.
314 */
315
316/*--------------------------------------------------------------------------*/
317
318/* Functions are provided here to allow quick mass access to register values
319   for display.  There is no comparable need for quick mass update, so writing
320   should be via Assign().
321 */
322
323typedef struct Dbg_RegSet {
324    ARMword
325        user[15],
326        pc,
327        psr,
328        fiq[7],
329        spsr_fiq,
330        irq[2],
331        spsr_irq,
332        svc[2],
333        spsr_svc,
334        abort[2],
335        spsr_abort,
336        undef[2],
337        spsr_undef;
338} Dbg_RegSet;
339
340/* bits in the modemask argument for ReadRegisters */
341
342#define Dbg_MM_User     1
343#define Dbg_MM_FIQ      2
344#define Dbg_MM_IRQ      4
345#define Dbg_MM_SVC      8
346#define Dbg_MM_Abort 0x10
347#define Dbg_MM_Undef 0x20
348#define Dbg_MM_System 0x40
349
350Dbg_Error Dbg_ReadRegisters(Dbg_MCState *state, Dbg_RegSet *regs, int modemask);
351
352Dbg_Error Dbg_WriteRegister(Dbg_MCState *state, int rno, int modemask, ARMword val);
353
354int Dbg_StringToMode(const char *name);
355
356int Dbg_ModeToModeMask(ARMword mode);
357
358/* Some implementations of the FP instruction set keep FP values loaded into
359   registers in their unconverted format, converting only when necessary.
360   Some RDI implementations deliver these values uninterpreted.
361   (For the rest, register values will always have type F_Extended).
362 */
363
364typedef enum { F_Single, F_Double, F_Extended, F_Packed, /* fpe340 values */
365               F_Internal,                               /* new fpe : mostly as extended */
366               F_None } Dbg_FPType;
367
368typedef struct { ARMword w[3]; } Dbg_TargetExtendedVal;
369typedef struct { ARMword w[3]; } Dbg_TargetPackedVal;
370typedef struct { ARMword w[2]; } Dbg_TargetDoubleVal;
371typedef struct { ARMword w[1]; } Dbg_TargetFloatVal;
372
373typedef union { Dbg_TargetExtendedVal e; Dbg_TargetPackedVal p;
374                Dbg_TargetDoubleVal d; Dbg_TargetFloatVal f; } Dbg_TargetFPVal;
375
376#define TargetSizeof_Extended 12
377#define TargetSizeof_Packed   12
378#define TargetSizeof_Double   8
379#define TargetSizeof_Float    4
380
381typedef struct Dbg_FPRegVal {
382     Dbg_FPType type;
383     Dbg_TargetFPVal v;
384} Dbg_FPRegVal;
385
386typedef struct Dbg_FPRegSet {
387    Dbg_FPRegVal f[8];
388    ARMword fpsr, fpcr;
389} Dbg_FPRegSet;
390
391Dbg_Error Dbg_ReadFPRegisters(Dbg_MCState *state, Dbg_FPRegSet *regs);
392
393Dbg_Error Dbg_WriteFPRegisters(Dbg_MCState *state, int32 mask, Dbg_FPRegSet *regs);
394
395Dbg_Error Dbg_FPRegToDouble(DbleBin *d, Dbg_FPRegVal const *f);
396/* Converts from a FP register value (in any format) to a double with
397   approximately the same value (or returns Dbg_Err_Overflow)
398 */
399
400void Dbg_DoubleToFPReg(Dbg_FPRegVal *f, DbleBin const *d);
401/* Converts the double <d> to a Dbg_FPRegVal with type F_Extended */
402
403/*--------------------------------------------------------------------------*/
404
405#include "dbg_cp.h"
406
407Dbg_Error Dbg_DescribeCoPro(Dbg_MCState *state, int cpnum, Dbg_CoProDesc *p);
408
409Dbg_Error Dbg_DescribeCoPro_RDI(Dbg_MCState *state, int cpnum, Dbg_CoProDesc *p);
410
411Dbg_Error Dbg_ReadCPRegisters(Dbg_MCState *state, int cpnum, ARMword *regs);
412
413Dbg_Error Dbg_WriteCPRegisters(Dbg_MCState *state, int cpnum, int32 mask, ARMword *regs);
414
415/*--------------------------------------------------------------------------*/
416
417Dbg_Error Dbg_ReadWords(
418    Dbg_MCState *state,
419    ARMword *words, ARMaddress addr, unsigned count);
420/* Reads a number of (32-bit) words from target store.  The values are in host
421   byte order; if they are also to be interpreted as bytes Dbg_SwapByteOrder()
422   must be called to convert to target byte order.
423 */
424
425Dbg_Error Dbg_WriteWords(
426    Dbg_MCState *state,
427    ARMaddress addr, const ARMword *words, unsigned count);
428/* Writes a number of (32-bit) words to target store.  The values are in host
429   byte order (if what is being written is actually a byte string it must be
430   converted by Dbg_SwapByteOrder()).
431 */
432
433Dbg_Error Dbg_ReadHalf(Dbg_MCState *state, ARMhword *val, ARMaddress addr);
434Dbg_Error Dbg_WriteHalf(Dbg_MCState *state, ARMaddress addr, ARMword val);
435
436Dbg_Error Dbg_ReadBytes(Dbg_MCState *state, Dbg_Byte *val, ARMaddress addr, unsigned count);
437Dbg_Error Dbg_WriteBytes(Dbg_MCState *state, ARMaddress addr, const Dbg_Byte *val, unsigned count);
438
439void Dbg_HostWords(Dbg_MCState *state, ARMword *words, unsigned wordcount);
440/* (A noop unless host and target bytesexes differ) */
441
442ARMword Dbg_HostWord(Dbg_MCState *state, ARMword v);
443
444ARMhword Dbg_HostHalf(Dbg_MCState *state, ARMword v);
445
446/*--------------------------------------------------------------------------*/
447
448/* Types describing various aspects of position within code.
449   There are rather a lot of these, in the interests of describing precisely
450   what fields must be present (rather than having a single type with many
451   fields which may or may not be valid according to context).
452 */
453
454typedef struct Dbg_LLPos {
455    Dbg_SymTable *st;
456    char *llsym;
457    ARMaddress offset;
458} Dbg_LLPos;
459
460typedef struct Dbg_File {
461    Dbg_SymTable *st;
462    char *file;
463} Dbg_File;
464
465typedef struct Dbg_Line {
466    unsigned32 line;      /* linenumber in the file */
467    unsigned16 statement, /* within the line (1-based) */
468               charpos;   /* ditto */
469} Dbg_Line;
470/* As an output value from toolbox functions, both statement and charpos are set
471   if the version of the debugger tables for the section concerned permits.
472   On input, <charpos> is used only if <statement> is 0 (in which case, if
473   <charpos> is non-0, Dbg_Err_DbgTableVersion is returned if the version of
474   the debugger tables concerned is too early.
475 */
476
477typedef struct Dbg_FilePos {
478    Dbg_File f;
479    Dbg_Line line;
480} Dbg_FilePos;
481
482typedef struct Dbg_ProcDesc {
483    Dbg_File f;
484    char *name;
485} Dbg_ProcDesc;
486
487typedef struct Dbg_ProcPos {
488    Dbg_ProcDesc p;
489    Dbg_Line line;
490} Dbg_ProcPos;
491
492/* Support for conversions between position representations */
493
494Dbg_Error Dbg_ProcDescToLine(Dbg_MCState *state, Dbg_ProcDesc *proc, Dbg_Line *line);
495/* If proc->f.file is null (and there is just one function proc->name), it is
496   updated to point to the name of the file containing (the start of)
497   proc->name.
498 */
499
500Dbg_Error Dbg_FilePosToProc(Dbg_MCState *state, const Dbg_FilePos *pos, char **procname);
501
502/* Conversions from position representations to and from code addresses */
503
504Dbg_Error Dbg_AddressToProcPos(
505    Dbg_MCState *state, ARMaddress addr,
506    Dbg_ProcPos *pos);
507Dbg_Error Dbg_AddressToLLPos(
508    Dbg_MCState *state, ARMaddress addr,
509    Dbg_LLPos *pos, Dbg_LLSymType *res_type, int system_names);
510
511Dbg_Error Dbg_ProcPosToAddress(
512    Dbg_MCState *state, const Dbg_ProcPos *pos,
513    ARMaddress *res);
514Dbg_Error Dbg_LLPosToAddress(
515    Dbg_MCState *state, const Dbg_LLPos *pos,
516    ARMaddress *res);
517
518typedef struct {
519    ARMaddress start, end;
520} Dbg_AddressRange;
521
522typedef Dbg_Error Dbg_AddressRangeProc(void *arg, int32 first, int32 last, Dbg_AddressRange const *range);
523
524Dbg_Error Dbg_MapAddressRangesForFileRange(
525    Dbg_MCState *state,
526    Dbg_SymTable *st, const char *f, int32 first, int32 last, Dbg_AddressRangeProc *p, void *arg);
527
528typedef struct Dbg_Environment Dbg_Environment;
529/* A Dbg_Environment describes the context required to make sense of a variable
530   name and access its value.  Its format is not revealed.  Dbg_Environment
531   values are allocated by Dbg_NewEnvironment() and discarded by
532   Dbg_DeleteEnvironment().
533 */
534
535Dbg_Environment *Dbg_NewEnvironment(Dbg_MCState *state);
536void Dbg_DeleteEnvironment(Dbg_MCState *state, Dbg_Environment *env);
537
538Dbg_Error Dbg_StringToEnv(
539    Dbg_MCState *state, char *str, Dbg_Environment *resenv,
540    int forcontext, Dbg_Environment const *curenv);
541
542Dbg_Error Dbg_ProcPosToEnvironment(
543    Dbg_MCState *state, const Dbg_ProcPos *pos, int activation,
544    const Dbg_Environment *current, Dbg_Environment *res);
545
546/* Conversion from a position representation to an Dbg_Environment (as required
547   to access variable values).  Only a Dbg_ProcPos argument here; other
548   representations need to be converted first.
549
550   Returns <res> describing the <activation>th instance of the function
551   described by <pos>, up from the stack base if <activation> is negative,
552   else down from <current>.
553   If this function returns Dbg_Err_ActivationNotPresent, the result
554   Dbg_Environment is still valid for accessing non-auto variables.
555 */
556
557typedef struct Dbg_DeclSpec Dbg_DeclSpec;
558
559Dbg_Error Dbg_EnvToProcItem(
560    Dbg_MCState *state, Dbg_Environment const *env, Dbg_DeclSpec *proc);
561
562Dbg_Error Dbg_ContainingEnvironment(
563    Dbg_MCState *state, const Dbg_Environment *context, Dbg_Environment *res);
564/* Set <res> to describe the containing function, file if <context> is within
565   a top-level function (or error if <context> already describes a file).
566 */
567
568/*--------------------------------------------------------------------------*/
569
570/* ASD debug table pointers are not by themselves sufficient description,
571   since there's an implied section context.  Hence the DeclSpec and TypeSpec
572   structures.
573 */
574
575
576#ifndef Dbg_TypeSpec_Defined
577
578struct Dbg_DeclSpec { void *a; };
579
580#ifdef CALLABLE_COMPILER
581typedef void *Dbg_TypeSpec;
582
583/* The intention here is to give an alternative definition for Dbg_BasicType
584   which follows.
585 */
586
587#define Dbg_T_Void      xDbg_T_Void
588#define Dbg_T_Bool      xDbg_T_Bool
589#define Dbg_T_SByte     xDbg_T_SByte
590#define Dbg_T_SHalf     xDbg_T_Half
591#define Dbg_T_SWord     xDbg_T_SWord
592#define Dbg_T_UByte     xDbg_T_UByte
593#define Dbg_T_UHalf     xDbg_T_UHalf
594#define Dbg_T_UWord     xDbg_T_UWord
595#define Dbg_T_Float     xDbg_T_Float
596#define Dbg_T_Double    xDbg_T_Double
597#define Dbg_T_LDouble   xDbg_T_LDouble
598#define Dbg_T_Complex   xDbg_T_Complex
599#define Dbg_T_DComplex  xDbg_T_DComplex
600#define Dbg_T_String    xDbg_T_String
601#define Dbg_T_Function  xDbg_T_Function
602
603#define Dbg_BasicType   xDbg_BaiscType
604#define Dbg_PrimitiveTypeToTypeSpec xDbg_PrimitiveTypeToTypeSpec
605
606#else
607/* We want a Dbg_TypeSpec to be a an opaque type, but of known size (so the
608   toolbox's clients can allocate the store to hold one); unfortunately, we
609   can do this only by having one definition for the toolbox's clients and
610   one (elsewhere) for the toolbox itself.
611 */
612
613typedef struct Dbg_TypeSpec Dbg_TypeSpec;
614struct Dbg_TypeSpec { void *a; int32 b; };
615#endif /* CALLABLE_COMPILER */
616
617typedef enum {
618    Dbg_T_Void,
619
620    Dbg_T_Bool,
621
622    Dbg_T_SByte,
623    Dbg_T_SHalf,
624    Dbg_T_SWord,
625
626    Dbg_T_UByte,
627    Dbg_T_UHalf,
628    Dbg_T_UWord,
629
630    Dbg_T_Float,
631    Dbg_T_Double,
632    Dbg_T_LDouble,
633
634    Dbg_T_Complex,
635    Dbg_T_DComplex,
636
637    Dbg_T_String,
638
639    Dbg_T_Function
640} Dbg_BasicType;
641
642#endif
643
644void Dbg_PrimitiveTypeToTypeSpec(Dbg_TypeSpec *ts, Dbg_BasicType t);
645
646bool Dbg_TypeIsIntegral(Dbg_TypeSpec const *ts);
647
648bool Dbg_TypeIsPointer(Dbg_TypeSpec const *ts);
649
650bool Dbg_TypeIsFunction(Dbg_TypeSpec const *ts);
651
652bool Dbg_PruneType(Dbg_TypeSpec *tsres, Dbg_TypeSpec const *ts);
653/* Return to tsres a version of ts which has been pruned by the removal of all
654   toplevel typedefs. Result is YES if the result has changed.
655 */
656
657typedef Dbg_Error Dbg_FileProc(Dbg_MCState *state, const char *name, const Dbg_DeclSpec *procdef, void *arg);
658
659Dbg_Error Dbg_EnumerateFiles(Dbg_MCState *state, Dbg_SymTable *st, Dbg_FileProc *p, void *arg);
660/* The top level for a high level enumerate.  Lower levels are performed by
661   EnumerateDeclarations (below).
662 */
663
664typedef enum {
665    ds_Invalid,
666    ds_Type,
667    ds_Var,
668    ds_Proc,
669    ds_Enum,
670    ds_Function,
671    ds_Label
672} Dbg_DeclSort;
673
674Dbg_DeclSort Dbg_SortOfDeclSpec(Dbg_DeclSpec const *decl);
675
676char *Dbg_NameOfDeclSpec(Dbg_DeclSpec const *decl);
677
678Dbg_TypeSpec Dbg_TypeSpecOfDeclSpec(Dbg_DeclSpec const *decl);
679
680typedef enum {
681    cs_None,
682    cs_Extern,
683    cs_Static,
684    cs_Auto,
685    cs_Reg,
686    cs_Var,
687    cs_Farg,
688    cs_Fcarg,
689    cs_Local,
690    cs_Filtered,
691    cs_Globalreg
692} Dbg_StgClass;
693
694Dbg_StgClass Dbg_StgClassOfDeclSpec(Dbg_DeclSpec const *decl);
695
696bool Dbg_VarsAtSameAddress(Dbg_DeclSpec const *d1, Dbg_DeclSpec const *d2);
697
698bool Dbg_VarsDecribedForDeclSpec(Dbg_DeclSpec const *decl);
699
700int Dbg_ArgCountOfDeclSpec(Dbg_DeclSpec const *decl);
701
702typedef struct Dbg_DComplex { DbleBin r, i; } Dbg_DComplex;
703
704typedef union Dbg_ConstantVal {
705    int32 l;
706    unsigned32 u;
707    DbleBin d;
708    Dbg_DComplex fc;
709    ARMaddress a;
710    char *s;
711} Dbg_ConstantVal;
712
713typedef struct Dbg_Constant {
714    Dbg_TypeSpec type;
715    Dbg_ConstantVal val;
716} Dbg_Constant;
717
718typedef enum Dbg_ValueSort {
719    vs_register,
720    vs_store,
721    vs_constant,
722    vs_local,
723    vs_filtered,
724    vs_none,
725    vs_error
726} Dbg_ValueSort;
727
728/* vs_local allows the use of symbol table entries to describe entities within
729   the debugger's own address space, accessed in the same way as target
730   variables.
731   vs_filtered describes entities which may be read or written only via an
732   access function (eg r15)
733 */
734
735#define fpr_base 16
736/* There's only one register ValueSort (reflecting asd table StgClass);
737   fp register n is encoded as register n+fpr_base.
738 */
739
740typedef struct Dbg_Value Dbg_Value;
741
742typedef Dbg_Error Dbg_AccessFn(Dbg_MCState *state, int write, Dbg_Value *self, Dbg_Constant *c);
743/* <write> == 0: read a vs_filtered value, updating the value self.
744   <write> == 1: update a vs_filtered value, with the value described by c.
745   <self> allows use of the same Dbg_AccessFn for several different entities
746   (using different val.f.id fields).
747 */
748
749typedef Dbg_Error Dbg_FormatFn(int decode, char *b, ARMword *valp, void *formatarg);
750
751typedef struct { Dbg_AccessFn *f; int id; } Dbg_AccessFnRec;
752
753struct Dbg_Value {
754    Dbg_TypeSpec type;
755    Dbg_ValueSort sort;
756    Dbg_FormatFn *formatp;
757    void *formatarg;
758    int f77csize;
759    union {
760        struct { int no; ARMaddress frame; } r;
761        ARMaddress ptr;
762        Dbg_ConstantVal c;
763        void *localp;
764        Dbg_AccessFnRec f;
765        Dbg_Error err;
766    } val;
767};
768
769Dbg_Error Dbg_AddLLSymbol(Dbg_SymTable *st, char const *name, Dbg_LLSymType type, ARMword val);
770
771Dbg_Error Dbg_AddSymbol(Dbg_SymTable *st, char const *name, Dbg_Value const *val);
772
773typedef struct Dbg_DeclSpecF {
774  Dbg_DeclSpec decl;
775  Dbg_FormatFn *formatp;
776  void *formatarg;
777} Dbg_DeclSpecF;
778
779typedef Dbg_Error Dbg_DeclProc(Dbg_MCState *state, Dbg_Environment const *context,
780                       Dbg_DeclSpecF const *var, Dbg_DeclSort sort, int masked,
781                       void *arg);
782
783Dbg_Error Dbg_EnumerateDeclarations(Dbg_MCState *state, Dbg_Environment const *context,
784                            Dbg_DeclProc *p, void *arg);
785/* call p once for every declaration local to the function described by
786   <context> (or file if <context> describes a place outside a function).
787   p's argument <masked> is true if the variable is not visible, thanks to
788   a declaration in an inner scope.
789 */
790
791Dbg_Error Dbg_ValueOfVar(Dbg_MCState *state, const Dbg_Environment *context,
792                 const Dbg_DeclSpec *var, Dbg_Value *val);
793/* Different from Dbg_EvalExpr() in that the thing being evaluated is described
794   by a Dbg_DeclSpec (which must be for a variable), rather than a string
795   needing to be decoded and associated with a symbol-table item.  Intended to
796   be called from a Dbg_DeclProc called from Dbg_EnumerateDeclarations.
797 */
798
799Dbg_Error Dbg_EvalExpr(Dbg_MCState *state, Dbg_Environment const *context,
800               char const *expr, int flags, Dbg_Value *val);
801
802Dbg_Error Dbg_EvalExpr_ep(Dbg_MCState *state, Dbg_Environment const *context,
803                  char const *expr, char **exprend, int flags, Dbg_Value *val);
804
805/* Both Dbg_ValueOfVar and Dbg_EvalExpr mostly deliver a value still containing
806   an indirection (since it may be wanted as the lhs of an assignment)
807 */
808
809void Dbg_RealLocation(Dbg_MCState *state, Dbg_Value *val);
810/* If val describes a register, this may really be a register, or a place on
811   the stack where the register's value is saved. In the latter case, val
812   is altered to describe the save place. (In all others, it remains
813   unchanged).
814 */
815
816Dbg_Error Dbg_DereferenceValue(Dbg_MCState *state, const Dbg_Value *value, Dbg_Constant *c);
817/* This fails if <value> describes a structure or array, returning
818   Dbg_Err_TypeNotSimple
819 */
820
821typedef struct Dbg_Expr Dbg_Expr;
822/* The result of parsing an expression in an environment: its structure is not
823   revealed.  (Clients may wish to parse just once an expression which may be
824   evaluated often).  In support of which, the following two functions partition
825   the work of Dbg_EvalExpr().
826 */
827
828#define Dbg_exfl_heap 1    /* allocate Expr on the heap (FreeExpr must then be
829                              called to discard it).  Otherwise, it goes in a
830                              place overwritten by the next call to ParseExpr
831                              or EvalExpr
832                            */
833#define Dbg_exfl_needassign 2
834#define Dbg_exfl_lowlevel   4
835
836int Dbg_SetInputRadix(Dbg_MCState *state, int radix);
837char *Dbg_SetDefaultIntFormat(Dbg_MCState *state, char *format);
838
839Dbg_Error Dbg_ParseExpr(
840    Dbg_MCState *state, Dbg_Environment const *env, char *string,
841    char **end, Dbg_Expr **res, int flags);
842/* Just parse the argument string, returning a pointer to a parsed expression
843   and a pointer to the first non-white space character in the input string
844   which is not part of the parsed expression. (If macro expansion has taken
845   place, the returned pointer will not be into the argument string at all,
846   rather into the expanded version of it).
847 */
848
849Dbg_Error Dbg_ParseExprCheckEnd(
850    Dbg_MCState *state, Dbg_Environment const *env, char *string,
851    Dbg_Expr **res, int flags);
852/* As Dbg_ParseExpr, but the parsed expression is required completely to fill
853   the argument string (apart possibly for trailing whitespace), and an error
854   is returned if it does not.
855 */
856
857Dbg_Error Dbg_ParsedExprToValue(
858    Dbg_MCState *state, const Dbg_Environment *env, Dbg_Expr *expr, Dbg_Value *v);
859
860Dbg_Error Dbg_ReadDecl(
861    Dbg_MCState *state, Dbg_Environment const *env, char *string,
862    Dbg_TypeSpec *p, char **varp, int flags);
863/* Read a variable declaration, returing a description of the type of the
864   variable to p, and a pointer to its name to varp.
865 */
866
867bool Dbg_IsCastToArrayType(Dbg_MCState *state, Dbg_Expr *expr);
868
869void Dbg_FreeExpr(Dbg_Expr *expr);
870
871Dbg_Error Dbg_CopyType(Dbg_TypeSpec *tdest, Dbg_TypeSpec const *tsource);
872Dbg_Error Dbg_FreeCopiedType(Dbg_TypeSpec *ts);
873
874Dbg_Error Dbg_TypeOfExpr(Dbg_MCState *state, Dbg_Expr *tree, Dbg_TypeSpec *restype);
875
876Dbg_Error Dbg_ExprToVar(const Dbg_Expr *expr, Dbg_DeclSpec *var, Dbg_Environment *env);
877
878Dbg_Error Dbg_Assign(Dbg_MCState *state, const Dbg_Value *lv, const Dbg_Value *rv);
879
880typedef enum Dbg_TypeSort {
881  ts_simple,
882  ts_union,
883  ts_struct,
884  ts_array
885} Dbg_TypeSort;
886
887Dbg_TypeSort Dbg_TypeSortOfValue(Dbg_MCState *state, const Dbg_Value *val, int *fieldcount);
888
889Dbg_Error Dbg_TypeToChars(const Dbg_TypeSpec *var, Dbg_BufDesc *buf);
890
891Dbg_Error Dbg_TypeSize(Dbg_MCState *state, const Dbg_TypeSpec *type, unsigned32 *res);
892
893typedef int Dbg_ValToChars_cb(Dbg_MCState *state, Dbg_Value *subval, const char *fieldname,
894                          Dbg_BufDesc *buf, void *arg);
895
896Dbg_Error Dbg_ValToChars(Dbg_MCState *state, Dbg_Value *val, int base,
897                 Dbg_ValToChars_cb *cb, void *arg,
898                 const char *form, Dbg_BufDesc *buf);
899/*
900   <base> is used for (any size) integer values.
901   If <val> is of an array or structure type, <cb> is called for each element,
902   with <arg> as its last parameter, and <subbuf> describing the space remaining
903   in <buf>.  If <cb> returns 0, conversion ceases.
904 */
905
906Dbg_Error Dbg_NthElement(
907    Dbg_MCState *state,
908    const Dbg_Value *val, unsigned32 n, char **fieldname, Dbg_Value *subval);
909
910typedef Dbg_Error Dbg_HistoryProc(void *, int, Dbg_Value *);
911
912Dbg_Error Dbg_RegisterHistoryProc(Dbg_MCState *state, Dbg_HistoryProc *p, void *arg);
913
914typedef enum {
915  ls_cpu,
916  ls_store,
917  ls_copro,
918  ls_local,
919  ls_filtered
920} Dbg_LocSort;
921
922typedef struct {
923  Dbg_LocSort sort;
924  union {
925    struct { ARMaddress addr, size; } store;
926    struct { int modemask; int r; } cpu;
927    struct { int no; int r; } cp;
928    void *localp;
929    Dbg_AccessFnRec f;
930  } loc;
931} Dbg_Loc;
932
933typedef Dbg_Error Dbg_ObjectWriteProc(Dbg_MCState *state, Dbg_Loc const *loc);
934Dbg_Error Dbg_OnObjectWrite(Dbg_MCState *state, Dbg_ObjectWriteProc *p);
935/* Register function to be called back whenever the toolbox has written to any
936 * object accessible by the debuggee (or to local variables belonging to a
937 * toolbox client). The write has already been done.
938 * (To allow multiple toolbox clients to coexist).
939 */
940
941Dbg_Error Dbg_ObjectWritten(Dbg_MCState *state, Dbg_Loc const *loc);
942
943/*--------------------------------------------------------------------------*/
944
945/* Control of target program execution.
946   Currently, only synchronous operation is provided.
947   Execution could possibly be asynchronous where the target is a seperate
948   processor, but is necessarily synchronous if the target is Armulator.
949   Unfortunately, this may require modification to the RDI implementation
950   if multitasking is required but the the host system provides it only
951   cooperatively, or if there is no system-provided way to generate SIGINT.
952 */
953
954Dbg_Error Dbg_SetCommandline(Dbg_MCState *state, const char *args);
955/* Set the argument string to the concatenation of the name of the most
956   recently loaded image and args.
957 */
958
959typedef enum Dbg_ProgramState {
960    ps_notstarted,
961    /* Normal ways of stopping */
962    ps_atbreak, ps_atwatch, ps_stepdone,
963    ps_interrupted,
964    ps_stopped,
965    /* abnormal (but unsurprising) ways of stopping */
966    ps_lostwatch,
967    ps_branchthrough0, ps_undef, ps_caughtswi, ps_prefetch,
968    ps_abort, ps_addrexcept, ps_caughtirq, ps_caughtfiq,
969    ps_error,
970    /* only as a return value from Call() */
971    ps_callfailed, ps_callreturned,
972    /* internal inconsistencies */
973    ps_broken,                  /* target has "broken" */
974    ps_unknownbreak,
975    ps_unknown
976} Dbg_ProgramState;
977
978int Dbg_IsCallLink(Dbg_MCState *state, ARMaddress pc);
979
980typedef struct {
981    Dbg_FPRegVal fpres;
982    ARMword intres;
983} Dbg_CallResults;
984
985Dbg_CallResults *Dbg_GetCallResults(Dbg_MCState *state);
986
987#define Dbg_S_STATEMENTS 0
988#define Dbg_S_INSTRUCTIONS 1
989#define Dbg_S_STEPINTOPROCS 2
990
991Dbg_Error Dbg_Step(Dbg_MCState *state, int32 stepcount, int stepby, Dbg_ProgramState *status);
992/*  <stepby> is a combination of the Dbg_S_... values above */
993
994Dbg_Error Dbg_StepOut(Dbg_MCState *state, Dbg_ProgramState *status);
995
996bool Dbg_CanGo(Dbg_MCState *state);
997
998bool Dbg_IsExecuting(Dbg_MCState *state);
999
1000Dbg_Error Dbg_Go(Dbg_MCState *state, Dbg_ProgramState *status);
1001
1002Dbg_Error Dbg_Stop(Dbg_MCState *state);
1003/* Asynchronous Stop request, for call from SIGINT handler.  On return to the
1004   caller, the call of Dbg_Go, Dbg_Step or Dbg_Call which started execution
1005   should return ps_interrupted.
1006 */
1007
1008typedef void Dbg_ExecuteProc(Dbg_MCState *state, Dbg_ProgramState status);
1009Dbg_Error Dbg_OnExecute(Dbg_MCState *, Dbg_ExecuteProc *);
1010/* Register function to be called back whenever execution stops.
1011 * (To allow multiple toolbox clients to coexist).
1012 */
1013
1014Dbg_Error Dbg_SetReturn(Dbg_MCState *state,
1015                const Dbg_Environment *context, const Dbg_Value *value);
1016/* Prepare continuation by returning <value> from the function activation
1017   described by <context>.  (Dbg_Go() or Dbg_Step() actually perform the
1018   continuation).
1019 */
1020
1021Dbg_Error Dbg_SetExecution(Dbg_MCState *state, Dbg_Environment *context);
1022/* Set the pc in a high-level fashion */
1023
1024Dbg_Error Dbg_ProgramStateToChars(Dbg_MCState *state, Dbg_ProgramState event, Dbg_BufDesc *buf);
1025/* This is guaranteed to give a completely accurate description of <event> if
1026   this was the value returned by the most recent call of Dbg_Go, Dbg_Step,
1027   or Dbg_Call.
1028 */
1029
1030/*--------------------------------------------------------------------------*/
1031
1032Dbg_Error Dbg_CurrentEnvironment(Dbg_MCState *state, Dbg_Environment *context);
1033
1034Dbg_Error Dbg_PrevFrame(Dbg_MCState *state, Dbg_Environment *context);
1035/* towards the base of the stack */
1036
1037Dbg_Error Dbg_NextFrame(Dbg_MCState *state, Dbg_Environment *context);
1038/* away from the base of the stack */
1039
1040typedef struct Dbg_AnyPos {
1041    enum { pos_source, pos_ll, pos_none } postype;
1042    ARMaddress pc;
1043    union {
1044        Dbg_ProcPos source;
1045        Dbg_LLPos ll;
1046        ARMaddress none;
1047    } pos;
1048} Dbg_AnyPos;
1049
1050Dbg_Error Dbg_EnvironmentToPos(Dbg_MCState *state, const Dbg_Environment *context, Dbg_AnyPos *pos);
1051/* <pos> is set to a Dbg_ProcPos if these is one corresponding to <context>
1052   else a Dbg_LLPos if there is one.
1053 */
1054
1055/*--------------------------------------------------------------------------*/
1056
1057/* Source file management.
1058   Pretty vestigial.  Handles source path (per loaded image),
1059   and translates from line-number (as given in debugger tables) to character
1060   position (as required to access files)
1061 */
1062
1063Dbg_Error Dbg_ClearPaths(Dbg_MCState *state, Dbg_SymTable *st);
1064Dbg_Error Dbg_AddPath(Dbg_MCState *state, Dbg_SymTable *st, const char *path);
1065Dbg_Error Dbg_DeletePath(Dbg_MCState *state, Dbg_SymTable *st, const char *path);
1066
1067typedef enum {
1068  Dbg_PathsCleared,
1069  Dbg_PathAdded,
1070  Dbg_PathDeleted
1071} Dbg_PathAlteration;
1072
1073typedef void Dbg_PathAlteredProc(
1074    Dbg_MCState *state, Dbg_SymTable *st, char const *path,
1075    Dbg_PathAlteration sort);
1076
1077Dbg_Error Dbg_OnPathAlteration(Dbg_MCState *state, Dbg_PathAlteredProc *p);
1078/* Register function to be called back whenever one of the source path
1079 * modification functions above is called. (To allow multiple toolbox
1080 * clients to coexist).
1081 */
1082
1083typedef struct Dbg_FileRec Dbg_FileRec;
1084typedef struct {
1085  unsigned32 linecount;
1086  Dbg_FileRec *handle;
1087  char *fullname;
1088} Dbg_FileDetails;
1089
1090Dbg_Error Dbg_GetFileDetails(
1091    Dbg_MCState *state, const Dbg_File *fname, Dbg_FileDetails *res);
1092Dbg_Error Dbg_FinishedWithFile(Dbg_MCState *state, Dbg_FileRec *handle);
1093
1094Dbg_Error Dbg_GetFileDetails_fr(
1095    Dbg_MCState *state, Dbg_FileRec *handle, Dbg_FileDetails *res);
1096/* Refresh details about the file associated with <handle> (in particular,
1097 * its linecount).
1098 */
1099
1100Dbg_Error Dbg_FileLineLength(
1101    Dbg_MCState *state, Dbg_FileRec *handle, int32 lineno, int32 *len);
1102/* Return to <len> the length of line <lineno> of the file associated with
1103 * <handle> (without necessarily reading from the file).
1104 */
1105
1106Dbg_Error Dbg_GetFileLine_fr(
1107    Dbg_MCState *state, Dbg_FileRec *handle, int32 lineno, Dbg_BufDesc *buf);
1108/* Return to <buf> the contents of line <lineno> of the file associated with
1109 * <handle> (including its terminating newline).
1110 */
1111
1112Dbg_Error Dbg_StartFileAccess(Dbg_MCState *state, Dbg_FileRec *handle);
1113Dbg_Error Dbg_EndFileAccess(Dbg_MCState *state, Dbg_FileRec *handle);
1114/* These two calls bracket a sequence of calls to GetFileLine. Between the
1115 * calls, the toolbox is permitted to retain state allowing more rapid
1116 * access to text on the file associated with <handle>.
1117 */
1118
1119Dbg_Error Dbg_ControlSourceFileAccess(
1120    Dbg_MCState *state, uint32 cachesize, bool closefiles);
1121/* Control details of how the toolbox manages source files.
1122 *   If <cachesize> is non-zero, the text from the most recently accessed
1123 *     source files (of total size not to exceed <cachesize>) is saved in
1124 *     store on first access to the file; subsequent access to the text of
1125 *     the file uses this copy.
1126 *   If <closefiles> is true, no stream is left attached to uncached source
1127 *     files after Dbg_EndFileAccess has been closed. Otherwise, the toolbox
1128 *     may retain such streams, in order to improve access.
1129 */
1130
1131/*--------------------------------------------------------------------------*/
1132
1133/* disassembly */
1134
1135/*
1136 ? More exact control is wanted here, but that requires a more complicated
1137 ? disass callback interface.
1138 */
1139
1140typedef const char *Dbg_SWI_Decode(Dbg_MCState *state, ARMword swino);
1141
1142Dbg_Error Dbg_InstructionAt(Dbg_MCState *state, ARMaddress addr,
1143                    int isize, ARMhword *inst, Dbg_SymTable *st,
1144                    Dbg_SWI_Decode *swi_name, Dbg_BufDesc *buf, int *length);
1145/* <isize> describes the form of disassembly wanted: 2 for 16-bit, 4 for 32-bit,
1146 * 0 for 16- or 32-bit depending whether addr addresses 16- or 32-bit code.
1147 * <inst> is a pointer to a pair of halfwords *in target byte order*
1148 * Possibly only the first halfword will be consumed: the number of bytes used
1149 * is returned via <length>.
1150 */
1151
1152/*--------------------------------------------------------------------------*/
1153
1154int Dbg_RDIOpen(Dbg_MCState *state, unsigned type);
1155int Dbg_RDIInfo(Dbg_MCState *state, unsigned type, ARMword *arg1, ARMword *arg2);
1156
1157/*--------------------------------------------------------------------------*/
1158
1159typedef enum {
1160    Dbg_Point_Toolbox,
1161    Dbg_Point_RDI_Unknown,
1162    Dbg_Point_RDI_SW,
1163    Dbg_Point_RDI_HW
1164} Dbg_PointType;
1165
1166/* breakpoint management
1167   Associated with a breakpoint there may be any of
1168     a count
1169     an expression
1170     a function
1171   the breakpoint is activated if
1172        the expression evaluates to a non-zero value (or fails to evaluate).
1173     && decrementing the count reaches zero (the count is then reset to its
1174        initial value).
1175     && the function, called with the breakpoint address as argument, returns
1176        a non-zero value.
1177?  (The order here may be open to debate.  Note that the first two are in
1178    the opposite order in armsd, but I think this order more rational)
1179 */
1180
1181typedef enum Dbg_BreakPosType {
1182    bt_procpos,
1183    bt_procexit,
1184    bt_address
1185} Dbg_BreakPosType;
1186
1187typedef union {
1188      Dbg_ProcPos procpos;
1189      Dbg_ProcDesc procexit;
1190      ARMaddress address;
1191} Dbg_BreakPosPos;
1192
1193typedef struct Dbg_BreakPos {
1194    Dbg_BreakPosType sort;
1195    Dbg_BreakPosPos loc;
1196} Dbg_BreakPos;
1197
1198typedef int Dbg_BPProc(Dbg_MCState *state, void *BPArg, Dbg_BreakPos *where);
1199
1200typedef struct Dbg_BreakStatus {
1201    int index;
1202    int initcount, countnow;
1203    Dbg_BreakPos where;
1204    char *expr;
1205    Dbg_BPProc *p; void *p_arg;
1206    int incomplete;
1207    Dbg_PointType type;
1208    ARMword hwresource;
1209} Dbg_BreakStatus;
1210
1211Dbg_Error Dbg_StringToBreakPos(
1212    Dbg_MCState *state, Dbg_Environment *env, char const *str, size_t len,
1213    Dbg_BreakPos *bpos, char *b);
1214
1215Dbg_Error Dbg_SetBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where,
1216                    int count,
1217                    const char *expr,
1218                    Dbg_BPProc *p, void *arg);
1219Dbg_Error Dbg_SetBreakPoint16(Dbg_MCState *state, Dbg_BreakPos *where,
1220                    int count,
1221                    const char *expr,
1222                    Dbg_BPProc *p, void *arg);
1223Dbg_Error Dbg_SetBreakPointNaturalSize(Dbg_MCState *state, Dbg_BreakPos *where,
1224                    int count,
1225                    const char *expr,
1226                    Dbg_BPProc *p, void *arg);
1227/* Setting a breakpoint at the same address as a previous breakpoint
1228   completely removes the previous one.
1229 */
1230
1231Dbg_Error Dbg_DeleteBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);
1232
1233Dbg_Error Dbg_SuspendBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);
1234/* Temporarily remove the break point (until Reinstated) but leave intact
1235   its associated expr, the value its count has reached, etc.
1236?  The debugger toolbox itself wants this, but I'm not sure what use a client
1237   could have for it.  Ditto Reinstate...
1238 */
1239
1240Dbg_Error Dbg_ReinstateBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);
1241/* Undo the effect of Dbg_SuspendBreakPoint
1242 */
1243
1244Dbg_Error Dbg_DeleteAllBreakPoints(Dbg_MCState *state);
1245
1246Dbg_Error Dbg_SuspendAllBreakPoints(Dbg_MCState *state);
1247
1248Dbg_Error Dbg_ReinstateAllBreakPoints(Dbg_MCState *state);
1249
1250typedef Dbg_Error Dbg_BPEnumProc(Dbg_MCState *state, Dbg_BreakStatus *status, void *arg);
1251
1252Dbg_Error Dbg_EnumerateBreakPoints(Dbg_MCState *state, Dbg_BPEnumProc *p, void *arg);
1253
1254Dbg_Error Dbg_BreakPointStatus(Dbg_MCState *state,
1255                       const Dbg_BreakPos *where, Dbg_BreakStatus *status);
1256
1257typedef void Dbg_BreakAlteredProc(Dbg_MCState *state, ARMaddress addr, bool set);
1258Dbg_Error Dbg_OnBreak(Dbg_MCState *state, Dbg_BreakAlteredProc *p);
1259/* Register function to be called back whenever a breakpoint is set or
1260 * cleared. (To allow multiple toolbox clients to coexist).
1261 */
1262
1263bool Dbg_StoppedAtBreakPoint(Dbg_MCState *state, const Dbg_BreakPos *where);
1264/* Called after execution which resulted in ps_atbreak, to find out whether
1265   the specified breakpoint was hit (could be >1, eg. exit break and another
1266   high-level breakpoint at the same position).
1267   Returns NO if specified breakpoint not found, or execution didn't stop
1268   with ps_atbreak status.
1269 */
1270
1271/*--------------------------------------------------------------------------*/
1272
1273typedef struct {
1274  Dbg_Value val;
1275  char *name;
1276} Dbg_WatchPos;
1277
1278typedef int Dbg_WPProc(Dbg_MCState *state, void *WPArg, Dbg_WatchPos *where);
1279
1280typedef struct Dbg_WPStatus {
1281    int index;
1282    int initcount, countnow;
1283    Dbg_WatchPos what, target;
1284    char *expr;
1285    Dbg_WPProc *p; void *p_arg;
1286    Dbg_PointType type;
1287    ARMword hwresource;
1288    int skip;
1289} Dbg_WPStatus;
1290
1291Dbg_Error Dbg_SetWatchPoint(
1292    Dbg_MCState *state, Dbg_Environment *context, char const *watchee,
1293    char const *target,
1294    int count,
1295    char const *expr,
1296    Dbg_WPProc *p, void *arg);
1297
1298/* Cause a watchpoint event if the value of <watchee> changes to the value of
1299   <target> (or changes at all if <target> is NULL).  <watchee> should
1300   evaluate either to an L-value (when the size of the object being watched is
1301   determined by its type) or to an integer constant (when the word with this
1302   address is watched).
1303 */
1304
1305Dbg_Error Dbg_DeleteWatchPoint(Dbg_MCState *state, Dbg_Environment *context, char const *watchee);
1306
1307
1308Dbg_Error Dbg_SetWatchPoint_V(
1309    Dbg_MCState *state,
1310    char const *name, Dbg_Value const *val, char const *tname, Dbg_Value const *tval,
1311    int count,
1312    char const *expr,
1313    Dbg_WPProc *p, void *arg);
1314
1315Dbg_Error Dbg_DeleteWatchPoint_V(Dbg_MCState *state, Dbg_Value const *val);
1316
1317
1318Dbg_Error Dbg_DeleteAllWatchPoints(Dbg_MCState *state);
1319
1320typedef Dbg_Error Dbg_WPEnumProc(Dbg_MCState *state, Dbg_WPStatus const *watchee, void *arg);
1321
1322Dbg_Error Dbg_EnumerateWatchPoints(Dbg_MCState *state, Dbg_WPEnumProc *p, void *arg);
1323
1324Dbg_Error Dbg_WatchPointStatus(Dbg_MCState *state,
1325                       Dbg_WatchPos const *where, Dbg_WPStatus *status);
1326
1327typedef void Dbg_WPRemovedProc(void *arg, Dbg_WPStatus const *wp);
1328Dbg_Error Dbg_RegisterWPRemovalProc(Dbg_MCState *state, Dbg_WPRemovedProc *p, void *arg);
1329/* When a watchpoint goes out of scope it is removed by the toolbox, and the
1330   function registered here gets called back to adjust its view
1331 */
1332
1333typedef void Dbg_WatchAlteredProc(Dbg_MCState *state, Dbg_Value const *where, bool set);
1334Dbg_Error Dbg_OnWatch(Dbg_MCState *state, Dbg_WatchAlteredProc *p);
1335/* Register function to be called back whenever a watchpoint is set or
1336 * cleared. (To allow multiple toolbox clients to coexist).
1337 */
1338
1339/*--------------------------------------------------------------------------*/
1340
1341Dbg_Error Dbg_ProfileLoad(Dbg_MCState *state);
1342
1343Dbg_Error Dbg_ProfileStart(Dbg_MCState *state, ARMword interval);
1344Dbg_Error Dbg_ProfileStop(Dbg_MCState *state);
1345
1346Dbg_Error Dbg_ProfileClear(Dbg_MCState *state);
1347
1348Dbg_Error Dbg_WriteProfile(Dbg_MCState *state, char const *filename,
1349                           char const *toolid, char const *arg);
1350
1351/*--------------------------------------------------------------------------*/
1352
1353Dbg_Error Dbg_ConnectChannel_ToHost(Dbg_MCState *state, RDICCProc_ToHost *p, void *arg);
1354Dbg_Error Dbg_ConnectChannel_FromHost(Dbg_MCState *state, RDICCProc_FromHost *p, void *arg);
1355
1356/*--------------------------------------------------------------------------*/
1357
1358/* Configuration data management */
1359
1360Dbg_Error Dbg_LoadConfigData(Dbg_MCState *state, char const *filename);
1361
1362Dbg_Error Dbg_SelectConfig(
1363    Dbg_MCState *state,
1364    RDI_ConfigAspect aspect, char const *name, RDI_ConfigMatchType matchtype,
1365    unsigned versionreq, unsigned *versionp);
1366
1367Dbg_Error Dbg_ParseConfigVersion(
1368    char const *s, RDI_ConfigMatchType *matchp, unsigned *versionp);
1369
1370typedef Dbg_Error Dbg_ConfigEnumProc(Dbg_MCState *state, RDI_ConfigDesc const *desc, void *arg);
1371
1372Dbg_Error Dbg_EnumerateConfigs(Dbg_MCState *state, Dbg_ConfigEnumProc *p, void *arg);
1373
1374/*--------------------------------------------------------------------------*/
1375
1376/* Angel OS support */
1377
1378Dbg_Error Dbg_CreateTask(Dbg_MCState **statep, Dbg_MCState *parent, bool inherit);
1379/* This is called when a task is to be debugged which has not been debugged
1380   before - ie. there is no existing Dbg_MCState for this task. It
1381   initialises a new Dbg_MCState and returns a pointer to it.
1382   <parent> is any valid previously-created MCCState. If <inherit> is TRUE,
1383   the new MCState inherits certain features from it (eg. symbols).
1384   Otherwise, only features which are the same across all tasks are inherited,
1385   (eg. global breakpoints).
1386 */
1387
1388Dbg_Error Dbg_DeleteTask(Dbg_MCState *state);
1389/* This is called when a task dies, and frees up everything which relates to that
1390   task which is controlled by armdbg.
1391 */
1392
1393Dbg_Error Dbg_DetachTask(Dbg_MCState *state);
1394
1395Dbg_Error Dbg_AttachTask(Dbg_MCState *state);
1396/* These are called to request a switch of the current task.  First
1397   Dbg_DetachTask should be called with the state of the old task.
1398   Dbg_DetachTask will ensure that any cached state held by armdbg for
1399   the old task is immediately written out to the target.
1400
1401   After Dbg_DetachTask is called and before Dbg_AttachTask is called
1402   the OS channel manager should tell the target that any future
1403   requests from the debugger will be fore the new task.
1404
1405   If the new task does not have an armdbg state structure
1406   already, then Dbg_CreateTask should be called to create one (see
1407   above).  Then Dbg_AttachTask is called to tell armdbg to treat the
1408   new armdbg state as the current task.
1409 */
1410
1411typedef Dbg_Error Dbg_TaskSwitchProc(void *arg, Dbg_MCState *newstate);
1412
1413Dbg_Error Dbg_OnTaskSwitch(Dbg_MCState *state, Dbg_TaskSwitchProc *fn, void *arg);
1414/* The front end may register a callback which gets called by armdbg whenever
1415   Dbg_AttachTask is called.  This callback tells the front end the new current
1416   Dbg_MCState it should use to call armdbg.
1417   [Note that this is only useful if there is one front end shared between all
1418    tasks rather than one front end per task]
1419   The value of <arg> passed to Dbg_OnTaskSwitch is passed to <fn>
1420   when it is called.
1421 */
1422
1423typedef Dbg_Error Dbg_RestartProc(
1424    void *arg, Dbg_MCState *curstate, Dbg_MCState **newstate);
1425
1426Dbg_Error Dbg_OnRestart(Dbg_MCState *state, Dbg_RestartProc *fn, void *arg);
1427/* This is used by the OS channels layer to register a callback which
1428   will be made by the debugger toolbox early in the process of resuming
1429   execution.
1430
1431   This callback must determine which task will be resumed when the target
1432   restarts execution.  If this is not already the current task then it must
1433   call Dbg_DetachTask and Dbg_AttachTask as decribed above to switch to the
1434   task about to be resumed and return the state for the new task in
1435   <newstate>.
1436
1437   This will ensure that armdbg updates the correct task on execution as well
1438   as ensuring that stepping over a breakpointed instruction on restarting
1439   happens correctly.
1440
1441   The value of <arg> passed to Dbg_OnRestart is passed to <fn>
1442   when it is called.
1443 */
1444
1445
1446#ifdef __cplusplus
1447}
1448#endif
1449
1450#endif
1451
1452/* End of armdbg.h */
1453