gdb/rdi-share/armdbg.h

   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$
  15  * Checkin $Date$
  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
  49 typedef unsigned32 ARMaddress;
  50 typedef unsigned32 ARMword;
  51 typedef unsigned16 ARMhword;
  52
  53 #include "dbg_conf.h"
  54 #include "dbg_rdi.h"
  55
  56 #ifdef __cplusplus
  57 extern "C"
  58 {
  59 #endif
  60
  61 typedef unsigned char Dbg_Byte;
  62
  63 typedef int Dbg_Error;
  64
  65 typedef 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
 127 typedef struct Dbg_BufDesc Dbg_BufDesc;
 128
 129 typedef void Dbg_BufferFullProc(Dbg_BufDesc *bd);
 130
 131 struct 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
 147 Dbg_Error Dbg_StringToBuf(Dbg_BufDesc *buf, char const *s);
 148 Dbg_Error Dbg_BufPrintf(Dbg_BufDesc *buf, char const *form, ...);
 149 #ifdef NLS
 150 Dbg_Error Dbg_MsgToBuf(Dbg_BufDesc *buf, msg_t t);
 151 Dbg_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
 156 Dbg_Error Dbg_CharToBuf(Dbg_BufDesc *buf, int ch);
 157
 158 int Dbg_CIStrCmp(char const *s1, char const *s2);
 159 /* Case-independent string comparison, interface as for strcmp */
 160
 161 int Dbg_CIStrnCmp(char const *s1, char const *s2, size_t n);
 162 /* Case-independent string comparison, interface as for strncmp */
 163
 164 void Dbg_ErrorToChars(Dbg_MCState *state, Dbg_Error err, Dbg_BufDesc *buf);
 165
 166 typedef 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
 173 typedef struct Dbg_CoProDesc Dbg_CoProDesc;
 174
 175 typedef 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
 180 typedef struct RDIProcVec RDIProcVec;
 181
 182 Dbg_Error Dbg_RequestReset(Dbg_MCState *);
 183
 184 Dbg_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
 190 void Dbg_Finalise(Dbg_MCState *state, bool targetdead);
 191
 192 typedef 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
 212 typedef struct Dbg_SymTable Dbg_SymTable;
 213
 214 typedef struct Dbg_ImageFragmentDesc {
 215     ARMaddress base, limit;
 216 } Dbg_ImageFragmentDesc;
 217
 218 typedef 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
 227 typedef 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
 236 Dbg_ImageDesc *Dbg_ImageAreas(Dbg_SymTable *st);
 237
 238 Dbg_SymTable *Dbg_LastImage(Dbg_MCState *state);
 239
 240 Dbg_SymTable *Dbg_NewSymTable(Dbg_MCState *state, const char *name);
 241
 242 Dbg_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
 249 typedef struct Dbg_SymInfo {
 250     int isize;
 251     ARMaddress addr;
 252     char *name;
 253 } Dbg_SymInfo;
 254
 255 Dbg_SymInfo *Dbg_AsmSym(Dbg_SymTable *st, ARMaddress addr);
 256 int32 Dbg_AsmAddr(Dbg_SymTable *st, int32 line);
 257 int32 Dbg_AsmLine(Dbg_SymTable *st, ARMaddress addr);
 258 int32 Dbg_AsmLinesInRange(Dbg_SymTable *st, ARMaddress start, ARMaddress end);
 259
 260 Dbg_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
 269 Dbg_Error Dbg_CallGLoadFile(Dbg_MCState *state, const char *filename, Dbg_SymTable **st);
 270
 271 typedef void Dbg_ImageLoadProc(Dbg_MCState *, Dbg_SymTable *);
 272 Dbg_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
 277 Dbg_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
 282 Dbg_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
 288 Dbg_Error Dbg_DeleteSymbols(Dbg_MCState *state, Dbg_SymTable **st);
 289
 290 typedef 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
 303 typedef Dbg_Error Dbg_SymProc(
 304     Dbg_MCState *state,
 305     const char *symbol, Dbg_LLSymType symtype, ARMaddress value,
 306     void *arg);
 307
 308 Dbg_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
 323 typedef 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
 350 Dbg_Error Dbg_ReadRegisters(Dbg_MCState *state, Dbg_RegSet *regs, int modemask);
 351
 352 Dbg_Error Dbg_WriteRegister(Dbg_MCState *state, int rno, int modemask, ARMword val);
 353
 354 int Dbg_StringToMode(const char *name);
 355
 356 int 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
 364 typedef 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
 368 typedef struct { ARMword w[3]; } Dbg_TargetExtendedVal;
 369 typedef struct { ARMword w[3]; } Dbg_TargetPackedVal;
 370 typedef struct { ARMword w[2]; } Dbg_TargetDoubleVal;
 371 typedef struct { ARMword w[1]; } Dbg_TargetFloatVal;
 372
 373 typedef 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
 381 typedef struct Dbg_FPRegVal {
 382      Dbg_FPType type;
 383      Dbg_TargetFPVal v;
 384 } Dbg_FPRegVal;
 385
 386 typedef struct Dbg_FPRegSet {
 387     Dbg_FPRegVal f[8];
 388     ARMword fpsr, fpcr;
 389 } Dbg_FPRegSet;
 390
 391 Dbg_Error Dbg_ReadFPRegisters(Dbg_MCState *state, Dbg_FPRegSet *regs);
 392
 393 Dbg_Error Dbg_WriteFPRegisters(Dbg_MCState *state, int32 mask, Dbg_FPRegSet *regs);
 394
 395 Dbg_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
 400 void 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
 407 Dbg_Error Dbg_DescribeCoPro(Dbg_MCState *state, int cpnum, Dbg_CoProDesc *p);
 408
 409 Dbg_Error Dbg_DescribeCoPro_RDI(Dbg_MCState *state, int cpnum, Dbg_CoProDesc *p);
 410
 411 Dbg_Error Dbg_ReadCPRegisters(Dbg_MCState *state, int cpnum, ARMword *regs);
 412
 413 Dbg_Error Dbg_WriteCPRegisters(Dbg_MCState *state, int cpnum, int32 mask, ARMword *regs);
 414
 415 /*--------------------------------------------------------------------------*/
 416
 417 Dbg_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
 425 Dbg_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
 433 Dbg_Error Dbg_ReadHalf(Dbg_MCState *state, ARMhword *val, ARMaddress addr);
 434 Dbg_Error Dbg_WriteHalf(Dbg_MCState *state, ARMaddress addr, ARMword val);
 435
 436 Dbg_Error Dbg_ReadBytes(Dbg_MCState *state, Dbg_Byte *val, ARMaddress addr, unsigned count);
 437 Dbg_Error Dbg_WriteBytes(Dbg_MCState *state, ARMaddress addr, const Dbg_Byte *val, unsigned count);
 438
 439 void Dbg_HostWords(Dbg_MCState *state, ARMword *words, unsigned wordcount);
 440 /* (A noop unless host and target bytesexes differ) */
 441
 442 ARMword Dbg_HostWord(Dbg_MCState *state, ARMword v);
 443
 444 ARMhword 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
 454 typedef struct Dbg_LLPos {
 455     Dbg_SymTable *st;
 456     char *llsym;
 457     ARMaddress offset;
 458 } Dbg_LLPos;
 459
 460 typedef struct Dbg_File {
 461     Dbg_SymTable *st;
 462     char *file;
 463 } Dbg_File;
 464
 465 typedef 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
 477 typedef struct Dbg_FilePos {
 478     Dbg_File f;
 479     Dbg_Line line;
 480 } Dbg_FilePos;
 481
 482 typedef struct Dbg_ProcDesc {
 483     Dbg_File f;
 484     char *name;
 485 } Dbg_ProcDesc;
 486
 487 typedef struct Dbg_ProcPos {
 488     Dbg_ProcDesc p;
 489     Dbg_Line line;
 490 } Dbg_ProcPos;
 491
 492 /* Support for conversions between position representations */
 493
 494 Dbg_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
 500 Dbg_Error Dbg_FilePosToProc(Dbg_MCState *state, const Dbg_FilePos *pos, char **procname);
 501
 502 /* Conversions from position representations to and from code addresses */
 503
 504 Dbg_Error Dbg_AddressToProcPos(
 505     Dbg_MCState *state, ARMaddress addr,
 506     Dbg_ProcPos *pos);
 507 Dbg_Error Dbg_AddressToLLPos(
 508     Dbg_MCState *state, ARMaddress addr,
 509     Dbg_LLPos *pos, Dbg_LLSymType *res_type, int system_names);
 510
 511 Dbg_Error Dbg_ProcPosToAddress(
 512     Dbg_MCState *state, const Dbg_ProcPos *pos,
 513     ARMaddress *res);
 514 Dbg_Error Dbg_LLPosToAddress(
 515     Dbg_MCState *state, const Dbg_LLPos *pos,
 516     ARMaddress *res);
 517
 518 typedef struct {
 519     ARMaddress start, end;
 520 } Dbg_AddressRange;
 521
 522 typedef Dbg_Error Dbg_AddressRangeProc(void *arg, int32 first, int32 last, Dbg_AddressRange const *range);
 523
 524 Dbg_Error Dbg_MapAddressRangesForFileRange(
 525     Dbg_MCState *state,
 526     Dbg_SymTable *st, const char *f, int32 first, int32 last, Dbg_AddressRangeProc *p, void *arg);
 527
 528 typedef 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
 535 Dbg_Environment *Dbg_NewEnvironment(Dbg_MCState *state);
 536 void Dbg_DeleteEnvironment(Dbg_MCState *state, Dbg_Environment *env);
 537
 538 Dbg_Error Dbg_StringToEnv(
 539     Dbg_MCState *state, char *str, Dbg_Environment *resenv,
 540     int forcontext, Dbg_Environment const *curenv);
 541
 542 Dbg_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
 557 typedef struct Dbg_DeclSpec Dbg_DeclSpec;
 558
 559 Dbg_Error Dbg_EnvToProcItem(
 560     Dbg_MCState *state, Dbg_Environment const *env, Dbg_DeclSpec *proc);
 561
 562 Dbg_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
 578 struct Dbg_DeclSpec { void *a; };
 579
 580 #ifdef CALLABLE_COMPILER
 581 typedef 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
 613 typedef struct Dbg_TypeSpec Dbg_TypeSpec;
 614 struct Dbg_TypeSpec { void *a; int32 b; };
 615 #endif /* CALLABLE_COMPILER */
 616
 617 typedef 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
 644 void Dbg_PrimitiveTypeToTypeSpec(Dbg_TypeSpec *ts, Dbg_BasicType t);
 645
 646 bool Dbg_TypeIsIntegral(Dbg_TypeSpec const *ts);
 647
 648 bool Dbg_TypeIsPointer(Dbg_TypeSpec const *ts);
 649
 650 bool Dbg_TypeIsFunction(Dbg_TypeSpec const *ts);
 651
 652 bool 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
 657 typedef Dbg_Error Dbg_FileProc(Dbg_MCState *state, const char *name, const Dbg_DeclSpec *procdef, void *arg);
 658
 659 Dbg_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
 664 typedef 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
 674 Dbg_DeclSort Dbg_SortOfDeclSpec(Dbg_DeclSpec const *decl);
 675
 676 char *Dbg_NameOfDeclSpec(Dbg_DeclSpec const *decl);
 677
 678 Dbg_TypeSpec Dbg_TypeSpecOfDeclSpec(Dbg_DeclSpec const *decl);
 679
 680 typedef 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
 694 Dbg_StgClass Dbg_StgClassOfDeclSpec(Dbg_DeclSpec const *decl);
 695
 696 bool Dbg_VarsAtSameAddress(Dbg_DeclSpec const *d1, Dbg_DeclSpec const *d2);
 697
 698 bool Dbg_VarsDecribedForDeclSpec(Dbg_DeclSpec const *decl);
 699
 700 int Dbg_ArgCountOfDeclSpec(Dbg_DeclSpec const *decl);
 701
 702 typedef struct Dbg_DComplex { DbleBin r, i; } Dbg_DComplex;
 703
 704 typedef 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
 713 typedef struct Dbg_Constant {
 714     Dbg_TypeSpec type;
 715     Dbg_ConstantVal val;
 716 } Dbg_Constant;
 717
 718 typedef 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
 740 typedef struct Dbg_Value Dbg_Value;
 741
 742 typedef 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
 749 typedef Dbg_Error Dbg_FormatFn(int decode, char *b, ARMword *valp, void *formatarg);
 750
 751 typedef struct { Dbg_AccessFn *f; int id; } Dbg_AccessFnRec;
 752
 753 struct 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
 769 Dbg_Error Dbg_AddLLSymbol(Dbg_SymTable *st, char const *name, Dbg_LLSymType type, ARMword val);
 770
 771 Dbg_Error Dbg_AddSymbol(Dbg_SymTable *st, char const *name, Dbg_Value const *val);
 772
 773 typedef struct Dbg_DeclSpecF {
 774   Dbg_DeclSpec decl;
 775   Dbg_FormatFn *formatp;
 776   void *formatarg;
 777 } Dbg_DeclSpecF;
 778
 779 typedef 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
 783 Dbg_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
 791 Dbg_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
 799 Dbg_Error Dbg_EvalExpr(Dbg_MCState *state, Dbg_Environment const *context,
 800                char const *expr, int flags, Dbg_Value *val);
 801
 802 Dbg_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
 809 void 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
 816 Dbg_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
 821 typedef 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
 836 int Dbg_SetInputRadix(Dbg_MCState *state, int radix);
 837 char *Dbg_SetDefaultIntFormat(Dbg_MCState *state, char *format);
 838
 839 Dbg_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
 849 Dbg_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
 857 Dbg_Error Dbg_ParsedExprToValue(
 858     Dbg_MCState *state, const Dbg_Environment *env, Dbg_Expr *expr, Dbg_Value *v);
 859
 860 Dbg_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
 867 bool Dbg_IsCastToArrayType(Dbg_MCState *state, Dbg_Expr *expr);
 868
 869 void Dbg_FreeExpr(Dbg_Expr *expr);
 870
 871 Dbg_Error Dbg_CopyType(Dbg_TypeSpec *tdest, Dbg_TypeSpec const *tsource);
 872 Dbg_Error Dbg_FreeCopiedType(Dbg_TypeSpec *ts);
 873
 874 Dbg_Error Dbg_TypeOfExpr(Dbg_MCState *state, Dbg_Expr *tree, Dbg_TypeSpec *restype);
 875
 876 Dbg_Error Dbg_ExprToVar(const Dbg_Expr *expr, Dbg_DeclSpec *var, Dbg_Environment *env);
 877
 878 Dbg_Error Dbg_Assign(Dbg_MCState *state, const Dbg_Value *lv, const Dbg_Value *rv);
 879
 880 typedef enum Dbg_TypeSort {
 881   ts_simple,
 882   ts_union,
 883   ts_struct,
 884   ts_array
 885 } Dbg_TypeSort;
 886
 887 Dbg_TypeSort Dbg_TypeSortOfValue(Dbg_MCState *state, const Dbg_Value *val, int *fieldcount);
 888
 889 Dbg_Error Dbg_TypeToChars(const Dbg_TypeSpec *var, Dbg_BufDesc *buf);
 890
 891 Dbg_Error Dbg_TypeSize(Dbg_MCState *state, const Dbg_TypeSpec *type, unsigned32 *res);
 892
 893 typedef int Dbg_ValToChars_cb(Dbg_MCState *state, Dbg_Value *subval, const char *fieldname,
 894                           Dbg_BufDesc *buf, void *arg);
 895
 896 Dbg_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
 906 Dbg_Error Dbg_NthElement(
 907     Dbg_MCState *state,
 908     const Dbg_Value *val, unsigned32 n, char **fieldname, Dbg_Value *subval);
 909
 910 typedef Dbg_Error Dbg_HistoryProc(void *, int, Dbg_Value *);
 911
 912 Dbg_Error Dbg_RegisterHistoryProc(Dbg_MCState *state, Dbg_HistoryProc *p, void *arg);
 913
 914 typedef enum {
 915   ls_cpu,
 916   ls_store,
 917   ls_copro,
 918   ls_local,
 919   ls_filtered
 920 } Dbg_LocSort;
 921
 922 typedef 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
 933 typedef Dbg_Error Dbg_ObjectWriteProc(Dbg_MCState *state, Dbg_Loc const *loc);
 934 Dbg_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
 941 Dbg_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
 954 Dbg_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
 959 typedef 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
 978 int Dbg_IsCallLink(Dbg_MCState *state, ARMaddress pc);
 979
 980 typedef struct {
 981     Dbg_FPRegVal fpres;
 982     ARMword intres;
 983 } Dbg_CallResults;
 984
 985 Dbg_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
 991 Dbg_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
 994 Dbg_Error Dbg_StepOut(Dbg_MCState *state, Dbg_ProgramState *status);
 995
 996 bool Dbg_CanGo(Dbg_MCState *state);
 997
 998 bool Dbg_IsExecuting(Dbg_MCState *state);
 999
1000 Dbg_Error Dbg_Go(Dbg_MCState *state, Dbg_ProgramState *status);
1001
1002 Dbg_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
1008 typedef void Dbg_ExecuteProc(Dbg_MCState *state, Dbg_ProgramState status);
1009 Dbg_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
1014 Dbg_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
1021 Dbg_Error Dbg_SetExecution(Dbg_MCState *state, Dbg_Environment *context);
1022 /* Set the pc in a high-level fashion */
1023
1024 Dbg_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
1032 Dbg_Error Dbg_CurrentEnvironment(Dbg_MCState *state, Dbg_Environment *context);
1033
1034 Dbg_Error Dbg_PrevFrame(Dbg_MCState *state, Dbg_Environment *context);
1035 /* towards the base of the stack */
1036
1037 Dbg_Error Dbg_NextFrame(Dbg_MCState *state, Dbg_Environment *context);
1038 /* away from the base of the stack */
1039
1040 typedef 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
1050 Dbg_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
1063 Dbg_Error Dbg_ClearPaths(Dbg_MCState *state, Dbg_SymTable *st);
1064 Dbg_Error Dbg_AddPath(Dbg_MCState *state, Dbg_SymTable *st, const char *path);
1065 Dbg_Error Dbg_DeletePath(Dbg_MCState *state, Dbg_SymTable *st, const char *path);
1066
1067 typedef enum {
1068   Dbg_PathsCleared,
1069   Dbg_PathAdded,
1070   Dbg_PathDeleted
1071 } Dbg_PathAlteration;
1072
1073 typedef void Dbg_PathAlteredProc(
1074     Dbg_MCState *state, Dbg_SymTable *st, char const *path,
1075     Dbg_PathAlteration sort);
1076
1077 Dbg_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
1083 typedef struct Dbg_FileRec Dbg_FileRec;
1084 typedef struct {
1085   unsigned32 linecount;
1086   Dbg_FileRec *handle;
1087   char *fullname;
1088 } Dbg_FileDetails;
1089
1090 Dbg_Error Dbg_GetFileDetails(
1091     Dbg_MCState *state, const Dbg_File *fname, Dbg_FileDetails *res);
1092 Dbg_Error Dbg_FinishedWithFile(Dbg_MCState *state, Dbg_FileRec *handle);
1093
1094 Dbg_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
1100 Dbg_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
1106 Dbg_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
1112 Dbg_Error Dbg_StartFileAccess(Dbg_MCState *state, Dbg_FileRec *handle);
1113 Dbg_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
1119 Dbg_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
1140 typedef const char *Dbg_SWI_Decode(Dbg_MCState *state, ARMword swino);
1141
1142 Dbg_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
1154 int Dbg_RDIOpen(Dbg_MCState *state, unsigned type);
1155 int Dbg_RDIInfo(Dbg_MCState *state, unsigned type, ARMword *arg1, ARMword *arg2);
1156
1157 /*--------------------------------------------------------------------------*/
1158
1159 typedef 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
1181 typedef enum Dbg_BreakPosType {
1182     bt_procpos,
1183     bt_procexit,
1184     bt_address
1185 } Dbg_BreakPosType;
1186
1187 typedef union {
1188       Dbg_ProcPos procpos;
1189       Dbg_ProcDesc procexit;
1190       ARMaddress address;
1191 } Dbg_BreakPosPos;
1192
1193 typedef struct Dbg_BreakPos {
1194     Dbg_BreakPosType sort;
1195     Dbg_BreakPosPos loc;
1196 } Dbg_BreakPos;
1197
1198 typedef int Dbg_BPProc(Dbg_MCState *state, void *BPArg, Dbg_BreakPos *where);
1199
1200 typedef 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
1211 Dbg_Error Dbg_StringToBreakPos(
1212     Dbg_MCState *state, Dbg_Environment *env, char const *str, size_t len,
1213     Dbg_BreakPos *bpos, char *b);
1214
1215 Dbg_Error Dbg_SetBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where,
1216                     int count,
1217                     const char *expr,
1218                     Dbg_BPProc *p, void *arg);
1219 Dbg_Error Dbg_SetBreakPoint16(Dbg_MCState *state, Dbg_BreakPos *where,
1220                     int count,
1221                     const char *expr,
1222                     Dbg_BPProc *p, void *arg);
1223 Dbg_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
1231 Dbg_Error Dbg_DeleteBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);
1232
1233 Dbg_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
1240 Dbg_Error Dbg_ReinstateBreakPoint(Dbg_MCState *state, Dbg_BreakPos *where);
1241 /* Undo the effect of Dbg_SuspendBreakPoint
1242  */
1243
1244 Dbg_Error Dbg_DeleteAllBreakPoints(Dbg_MCState *state);
1245
1246 Dbg_Error Dbg_SuspendAllBreakPoints(Dbg_MCState *state);
1247
1248 Dbg_Error Dbg_ReinstateAllBreakPoints(Dbg_MCState *state);
1249
1250 typedef Dbg_Error Dbg_BPEnumProc(Dbg_MCState *state, Dbg_BreakStatus *status, void *arg);
1251
1252 Dbg_Error Dbg_EnumerateBreakPoints(Dbg_MCState *state, Dbg_BPEnumProc *p, void *arg);
1253
1254 Dbg_Error Dbg_BreakPointStatus(Dbg_MCState *state,
1255                        const Dbg_BreakPos *where, Dbg_BreakStatus *status);
1256
1257 typedef void Dbg_BreakAlteredProc(Dbg_MCState *state, ARMaddress addr, bool set);
1258 Dbg_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
1263 bool 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
1273 typedef struct {
1274   Dbg_Value val;
1275   char *name;
1276 } Dbg_WatchPos;
1277
1278 typedef int Dbg_WPProc(Dbg_MCState *state, void *WPArg, Dbg_WatchPos *where);
1279
1280 typedef 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
1291 Dbg_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
1305 Dbg_Error Dbg_DeleteWatchPoint(Dbg_MCState *state, Dbg_Environment *context, char const *watchee);
1306
1307
1308 Dbg_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
1315 Dbg_Error Dbg_DeleteWatchPoint_V(Dbg_MCState *state, Dbg_Value const *val);
1316
1317
1318 Dbg_Error Dbg_DeleteAllWatchPoints(Dbg_MCState *state);
1319
1320 typedef Dbg_Error Dbg_WPEnumProc(Dbg_MCState *state, Dbg_WPStatus const *watchee, void *arg);
1321
1322 Dbg_Error Dbg_EnumerateWatchPoints(Dbg_MCState *state, Dbg_WPEnumProc *p, void *arg);
1323
1324 Dbg_Error Dbg_WatchPointStatus(Dbg_MCState *state,
1325                        Dbg_WatchPos const *where, Dbg_WPStatus *status);
1326
1327 typedef void Dbg_WPRemovedProc(void *arg, Dbg_WPStatus const *wp);
1328 Dbg_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
1333 typedef void Dbg_WatchAlteredProc(Dbg_MCState *state, Dbg_Value const *where, bool set);
1334 Dbg_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
1341 Dbg_Error Dbg_ProfileLoad(Dbg_MCState *state);
1342
1343 Dbg_Error Dbg_ProfileStart(Dbg_MCState *state, ARMword interval);
1344 Dbg_Error Dbg_ProfileStop(Dbg_MCState *state);
1345
1346 Dbg_Error Dbg_ProfileClear(Dbg_MCState *state);
1347
1348 Dbg_Error Dbg_WriteProfile(Dbg_MCState *state, char const *filename,
1349                            char const *toolid, char const *arg);
1350
1351 /*--------------------------------------------------------------------------*/
1352
1353 Dbg_Error Dbg_ConnectChannel_ToHost(Dbg_MCState *state, RDICCProc_ToHost *p, void *arg);
1354 Dbg_Error Dbg_ConnectChannel_FromHost(Dbg_MCState *state, RDICCProc_FromHost *p, void *arg);
1355
1356 /*--------------------------------------------------------------------------*/
1357
1358 /* Configuration data management */
1359
1360 Dbg_Error Dbg_LoadConfigData(Dbg_MCState *state, char const *filename);
1361
1362 Dbg_Error Dbg_SelectConfig(
1363     Dbg_MCState *state,
1364     RDI_ConfigAspect aspect, char const *name, RDI_ConfigMatchType matchtype,
1365     unsigned versionreq, unsigned *versionp);
1366
1367 Dbg_Error Dbg_ParseConfigVersion(
1368     char const *s, RDI_ConfigMatchType *matchp, unsigned *versionp);
1369
1370 typedef Dbg_Error Dbg_ConfigEnumProc(Dbg_MCState *state, RDI_ConfigDesc const *desc, void *arg);
1371
1372 Dbg_Error Dbg_EnumerateConfigs(Dbg_MCState *state, Dbg_ConfigEnumProc *p, void *arg);
1373
1374 /*--------------------------------------------------------------------------*/
1375
1376 /* Angel OS support */
1377
1378 Dbg_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
1388 Dbg_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
1393 Dbg_Error Dbg_DetachTask(Dbg_MCState *state);
1394
1395 Dbg_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
1411 typedef Dbg_Error Dbg_TaskSwitchProc(void *arg, Dbg_MCState *newstate);
1412
1413 Dbg_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
1423 typedef Dbg_Error Dbg_RestartProc(
1424     void *arg, Dbg_MCState *curstate, Dbg_MCState **newstate);
1425
1426 Dbg_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 */