git.sur5r.net Git - cc65/blob - src/dbginfo/dbginfo.h

   1 /*****************************************************************************/
   2 /*                                                                           */
   3 /*                                 dbginfo.h                                 */
   4 /*                                                                           */
   5 /*                         cc65 debug info handling                          */
   6 /*                                                                           */
   7 /*                                                                           */
   8 /*                                                                           */
   9 /* (C) 2010-2011, Ullrich von Bassewitz                                      */
  10 /*                Roemerstrasse 52                                           */
  11 /*                D-70794 Filderstadt                                        */
  12 /* EMail:         uz@cc65.org                                                */
  13 /*                                                                           */
  14 /*                                                                           */
  15 /* This software is provided 'as-is', without any expressed or implied       */
  16 /* warranty.  In no event will the authors be held liable for any damages    */
  17 /* arising from the use of this software.                                    */
  18 /*                                                                           */
  19 /* Permission is granted to anyone to use this software for any purpose,     */
  20 /* including commercial applications, and to alter it and redistribute it    */
  21 /* freely, subject to the following restrictions:                            */
  22 /*                                                                           */
  23 /* 1. The origin of this software must not be misrepresented; you must not   */
  24 /*    claim that you wrote the original software. If you use this software   */
  25 /*    in a product, an acknowledgment in the product documentation would be  */
  26 /*    appreciated but is not required.                                       */
  27 /* 2. Altered source versions must be plainly marked as such, and must not   */
  28 /*    be misrepresented as being the original software.                      */
  29 /* 3. This notice may not be removed or altered from any source              */
  30 /*    distribution.                                                          */
  31 /*                                                                           */
  32 /*****************************************************************************/
  33
  34
  35
  36 #ifndef DBGINFO_H
  37 #define DBGINFO_H
  38
  39
  40
  41 /* Allow usage from C++ */
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46
  47
  48 /*****************************************************************************/
  49 /*                                   Data                                    */
  50 /*****************************************************************************/
  51
  52
  53
  54 /* Data types used for addresses, sizes and line numbers. Change to "unsigned
  55  * long" if you ever want to run the code on a 16-bit machine.
  56  */
  57 typedef unsigned cc65_line;             /* Used to store line numbers */
  58 typedef unsigned cc65_addr;             /* Used to store (65xx) addresses */
  59 typedef unsigned cc65_size;             /* Used to store (65xx) sizes */
  60
  61 /* A value that is used to mark invalid ids */
  62 #define CC65_INV_ID     (~0U)
  63
  64
  65
  66 /*****************************************************************************/
  67 /*                             Debug info files                              */
  68 /*****************************************************************************/
  69
  70
  71
  72 /* Severity for cc65_parseerror */
  73 typedef enum {
  74     CC65_WARNING,
  75     CC65_ERROR,
  76 } cc65_error_severity;
  77
  78 /* Warnings/errors in cc65_read_dbginfo are passed via this struct */
  79 typedef struct cc65_parseerror cc65_parseerror;
  80 struct cc65_parseerror {
  81     cc65_error_severity type;           /* Type of error */
  82     const char*         name;           /* Name of input file */
  83     cc65_line           line;           /* Error line */
  84     unsigned            column;         /* Error column */
  85     char                errormsg[1];    /* Error message */
  86 };
  87
  88 /* Function that is called in case of parse errors */
  89 typedef void (*cc65_errorfunc) (const cc65_parseerror*);
  90
  91 /* Pointer to an opaque data structure containing information from the debug
  92  * info file. Actually a handle to the data in the file.
  93  */
  94 typedef const void* cc65_dbginfo;
  95
  96
  97
  98 cc65_dbginfo cc65_read_dbginfo (const char* filename, cc65_errorfunc errorfunc);
  99 /* Parse the debug info file with the given name. On success, the function
 100  * will return a pointer to an opaque cc65_dbginfo structure, that must be
 101  * passed to the other functions in this module to retrieve information.
 102  * errorfunc is called in case of warnings and errors. If the file cannot be
 103  * read successfully, NULL is returned.
 104  */
 105
 106 void cc65_free_dbginfo (cc65_dbginfo Handle);
 107 /* Free debug information read from a file */
 108
 109
 110
 111 /*****************************************************************************/
 112 /*                                 Libraries                                 */
 113 /*****************************************************************************/
 114
 115
 116
 117 /* Library information */
 118 typedef struct cc65_librarydata cc65_librarydata;
 119 struct cc65_librarydata {
 120     unsigned            library_id;     /* The internal library id */
 121     const char*         library_name;   /* Name of the library */
 122 };
 123
 124 typedef struct cc65_libraryinfo cc65_libraryinfo;
 125 struct cc65_libraryinfo {
 126     unsigned            count;          /* Number of data sets that follow */
 127     cc65_librarydata    data[1];        /* Data sets, number is dynamic */
 128 };
 129
 130
 131
 132 const cc65_libraryinfo* cc65_get_librarylist (cc65_dbginfo handle);
 133 /* Return a list of all libraries */
 134
 135 const cc65_libraryinfo* cc65_library_byid (cc65_dbginfo handle, unsigned id);
 136 /* Return information about a library with a specific id. The function
 137  * returns NULL if the id is invalid (no such library) and otherwise a
 138  * cc65_libraryinfo structure with one entry that contains the requested
 139  * library information.
 140  */
 141
 142 void cc65_free_libraryinfo (cc65_dbginfo handle, const cc65_libraryinfo* info);
 143 /* Free a library info record */
 144
 145
 146
 147 /*****************************************************************************/
 148 /*                                 Line info                                 */
 149 /*****************************************************************************/
 150
 151
 152
 153 /* Type of line */
 154 typedef enum {
 155     CC65_LINE_ASM,                      /* Assembler source */
 156     CC65_LINE_EXT,                      /* Externally supplied (= C) */
 157     CC65_LINE_MACRO,                    /* Macro expansion */
 158 } cc65_line_type;
 159
 160 /* Line information */
 161 typedef struct cc65_linedata cc65_linedata;
 162 struct cc65_linedata {
 163     unsigned            line_id;        /* Internal id of this record */
 164     unsigned            source_id;      /* Id of the source file */
 165     cc65_line           source_line;    /* Line number */
 166     cc65_line_type      line_type;      /* Type of line */
 167     unsigned            count;          /* Nesting counter for macros */
 168 };
 169
 170 typedef struct cc65_lineinfo cc65_lineinfo;
 171 struct cc65_lineinfo {
 172     unsigned            count;          /* Number of data sets that follow */
 173     cc65_linedata       data[1];        /* Data sets, number is dynamic */
 174 };
 175
 176
 177
 178 const cc65_lineinfo* cc65_line_byid (cc65_dbginfo handle, unsigned id);
 179 /* Return information about a line with a specific id. The function
 180  * returns NULL if the id is invalid (no such line) and otherwise a
 181  * cc65_lineinfo structure with one entry that contains the requested
 182  * module information.
 183  */
 184
 185 const cc65_lineinfo* cc65_line_bynumber (cc65_dbginfo handle,
 186                                          unsigned source_id,
 187                                          cc65_line line);
 188 /* Return line information for a source file/line number combination. The
 189  * function returns NULL if no line information was found.
 190  */
 191
 192 const cc65_lineinfo* cc65_line_bysource (cc65_dbginfo Handle, unsigned source_id);
 193 /* Return line information for a source file. The function returns NULL if the
 194  * file id is invalid.
 195  */
 196
 197 void cc65_free_lineinfo (cc65_dbginfo handle, const cc65_lineinfo* info);
 198 /* Free line info returned by one of the other functions */
 199
 200
 201
 202 /*****************************************************************************/
 203 /*                                  Modules                                  */
 204 /*****************************************************************************/
 205
 206
 207
 208 /* Module information */
 209 typedef struct cc65_moduledata cc65_moduledata;
 210 struct cc65_moduledata {
 211     unsigned            module_id;      /* The internal module id */
 212     const char*         module_name;    /* Name of the module */
 213     unsigned            source_id;      /* Id of the module main file */
 214     unsigned            library_id;     /* Id of the library if any */
 215     unsigned            scope_id;       /* Id of the main scope */
 216 };
 217
 218 typedef struct cc65_moduleinfo cc65_moduleinfo;
 219 struct cc65_moduleinfo {
 220     unsigned            count;          /* Number of data sets that follow */
 221     cc65_moduledata     data[1];        /* Data sets, number is dynamic */
 222 };
 223
 224
 225
 226 const cc65_moduleinfo* cc65_get_modulelist (cc65_dbginfo handle);
 227 /* Return a list of all modules */
 228
 229 const cc65_moduleinfo* cc65_module_byid (cc65_dbginfo handle, unsigned id);
 230 /* Return information about a module with a specific id. The function
 231  * returns NULL if the id is invalid (no such module) and otherwise a
 232  * cc65_moduleinfo structure with one entry that contains the requested
 233  * module information.
 234  */
 235
 236 void cc65_free_moduleinfo (cc65_dbginfo handle, const cc65_moduleinfo* info);
 237 /* Free a module info record */
 238
 239
 240
 241 /*****************************************************************************/
 242 /*                                   Spans                                   */
 243 /*****************************************************************************/
 244
 245
 246
 247 /* Span information */
 248 typedef struct cc65_spandata cc65_spandata;
 249 struct cc65_spandata {
 250     unsigned            span_id;        /* The internal span id */
 251     cc65_addr           span_start;     /* Start of the span */
 252     cc65_addr           span_end;       /* End of the span (inclusive!) */
 253     unsigned            segment_id;     /* Id of the segment */
 254 };
 255
 256 typedef struct cc65_spaninfo cc65_spaninfo;
 257 struct cc65_spaninfo {
 258     unsigned            count;          /* Number of data sets that follow */
 259     cc65_spandata       data[1];        /* Data sets, number is dynamic */
 260 };
 261
 262
 263
 264 const cc65_spaninfo* cc65_get_spanlist (cc65_dbginfo handle);
 265 /* Return a list of all spans. BEWARE: Large! */
 266
 267 const cc65_spaninfo* cc65_span_byid (cc65_dbginfo handle, unsigned id);
 268 /* Return information about a span with a specific id. The function
 269  * returns NULL if the id is invalid (no such span) and otherwise a
 270  * cc65_spaninfo structure with one entry that contains the requested
 271  * span information.
 272  */
 273
 274 const cc65_spaninfo* cc65_span_byaddr (cc65_dbginfo handle,
 275                                        unsigned long addr);
 276 /* Return span information for the given address. The function returns NULL
 277  * if no spans were found for this address.
 278  */
 279
 280 const cc65_spaninfo* cc65_span_byline (cc65_dbginfo handle, unsigned line_id);
 281 /* Return span information for the given source line. The function returns NULL
 282  * if the line id is invalid, otherwise the spans for this line (possibly zero).
 283  */
 284
 285 const cc65_spaninfo* cc65_span_byscope (cc65_dbginfo handle, unsigned scope_id);
 286 /* Return span information for the given scope. The function returns NULL if
 287  * the scope id is invalid, otherwise the spans for this scope (possibly zero).
 288  */
 289
 290 void cc65_free_spaninfo (cc65_dbginfo handle, const cc65_spaninfo* info);
 291 /* Free a span info record */
 292
 293
 294
 295 /*****************************************************************************/
 296 /*                               Source files                                */
 297 /*****************************************************************************/
 298
 299
 300
 301 /* Source file information */
 302 typedef struct cc65_sourcedata cc65_sourcedata;
 303 struct cc65_sourcedata {
 304     unsigned            source_id;      /* The internal file id */
 305     const char*         source_name;    /* Name of the file */
 306     unsigned long       source_size;    /* Size of file */
 307     unsigned long       source_mtime;   /* Modification time */
 308 };
 309
 310 typedef struct cc65_sourceinfo cc65_sourceinfo;
 311 struct cc65_sourceinfo {
 312     unsigned            count;          /* Number of data sets that follow */
 313     cc65_sourcedata     data[1];        /* Data sets, number is dynamic */
 314 };
 315
 316
 317
 318 const cc65_sourceinfo* cc65_get_sourcelist (cc65_dbginfo handle);
 319 /* Return a list of all source files */
 320
 321 const cc65_sourceinfo* cc65_source_byid (cc65_dbginfo handle, unsigned id);
 322 /* Return information about a source file with a specific id. The function
 323  * returns NULL if the id is invalid (no such source file) and otherwise a
 324  * cc65_sourceinfo structure with one entry that contains the requested
 325  * source file information.
 326  */
 327
 328 const cc65_sourceinfo* cc65_source_bymodule (cc65_dbginfo handle,
 329                                              unsigned module_id);
 330 /* Return information about the source files used to build a module. The
 331  * function returns NULL if the module id is invalid (no such module) and
 332  * otherwise a cc65_sourceinfo structure with one entry per source file.
 333  */
 334
 335 void cc65_free_sourceinfo (cc65_dbginfo handle, const cc65_sourceinfo* info);
 336 /* Free a source info record */
 337
 338
 339
 340 /*****************************************************************************/
 341 /*                                 Segments                                  */
 342 /*****************************************************************************/
 343
 344
 345
 346 /* Segment information.
 347  * Notes:
 348  *   - output_name may be NULL if the data wasn't written to the output file
 349  *     (example: bss segment)
 350  *   - output_offs is invalid if there is no output_name, and may not be of
 351  *     much use in case of a relocatable output file
 352  */
 353 typedef struct cc65_segmentdata cc65_segmentdata;
 354 struct cc65_segmentdata {
 355     unsigned            segment_id;     /* The internal segment id */
 356     const char*         segment_name;   /* Name of the segment */
 357     cc65_addr           segment_start;  /* Start address of segment */
 358     cc65_size           segment_size;   /* Size of segment */
 359     const char*         output_name;    /* Output file this seg was written to */
 360     unsigned long       output_offs;    /* Offset of this seg in output file */
 361 };
 362
 363 typedef struct cc65_segmentinfo cc65_segmentinfo;
 364 struct cc65_segmentinfo {
 365     unsigned            count;          /* Number of data sets that follow */
 366     cc65_segmentdata    data[1];        /* Data sets, number is dynamic */
 367 };
 368
 369
 370
 371 const cc65_segmentinfo* cc65_get_segmentlist (cc65_dbginfo handle);
 372 /* Return a list of all segments referenced in the debug information */
 373
 374 const cc65_segmentinfo* cc65_segment_byid (cc65_dbginfo handle, unsigned id);
 375 /* Return information about a segment with a specific id. The function returns
 376  * NULL if the id is invalid (no such segment) and otherwise a cc65_segmentinfo
 377  * structure with one entry that contains the requested segment information.
 378  */
 379
 380 const cc65_segmentinfo* cc65_segment_byname (cc65_dbginfo handle,
 381                                              const char* name);
 382 /* Return information about a segment with a specific name. The function
 383  * returns NULL if no segment with this name exists and otherwise a
 384  * cc65_segmentinfo structure with one entry that contains the requested
 385  * information.
 386  */
 387
 388 void cc65_free_segmentinfo (cc65_dbginfo handle, const cc65_segmentinfo* info);
 389 /* Free a segment info record */
 390
 391
 392
 393 /*****************************************************************************/
 394 /*                                  Symbols                                  */
 395 /*****************************************************************************/
 396
 397
 398
 399 /* Symbol information */
 400 typedef enum {
 401     CC65_SYM_EQUATE,
 402     CC65_SYM_LABEL,                     /* Some sort of address */
 403 } cc65_symbol_type;
 404
 405 /* Notes:
 406  *  - If the symbol is segment relative, the segment id gives segment
 407  *    information, otherwise it contains CC65_INV_ID.
 408  *  - If export_id is valid (not CC65_INV_ID), the symbol is an import and
 409  *    export_id allows to retrieve the corresponding export. The fields
 410  *    symbol_value and segment_id are taken from the export, since imports
 411  *    have no value or segments by itself. symbol_type and symbol_size are
 412  *    more or less unusable because they don't have a meaning for imports.
 413  *  - For normal symbols (not cheap locals) parent_id contains CC65_INV_ID.
 414  */
 415 typedef struct cc65_symboldata cc65_symboldata;
 416 struct cc65_symboldata {
 417     unsigned            symbol_id;      /* Id of symbol */
 418     const char*         symbol_name;    /* Name of symbol */
 419     cc65_symbol_type    symbol_type;    /* Type of symbol */
 420     cc65_size           symbol_size;    /* Size of symbol, 0 if unknown */
 421     long                symbol_value;   /* Value of symbol */
 422     unsigned            export_id;      /* For imports: Matching export */
 423     unsigned            segment_id;     /* Id of segment if any */
 424     unsigned            scope_id;       /* The scope this symbol is in */
 425     unsigned            parent_id;      /* Parent symbol for cheap locals */
 426 };
 427
 428 typedef struct cc65_symbolinfo cc65_symbolinfo;
 429 struct cc65_symbolinfo {
 430     unsigned            count;          /* Number of data sets that follow */
 431     cc65_symboldata     data[1];        /* Data sets, number is dynamic */
 432 };
 433
 434
 435
 436 const cc65_symbolinfo* cc65_symbol_byid (cc65_dbginfo handle, unsigned id);
 437 /* Return the symbol with a given id. The function returns NULL if no symbol
 438  * with this id was found.
 439  */
 440
 441 const cc65_symbolinfo* cc65_symbol_byname (cc65_dbginfo handle, const char* name);
 442 /* Return a list of symbols with a given name. The function returns NULL if
 443  * no symbol with this name was found.
 444  */
 445
 446 const cc65_symbolinfo* cc65_symbol_byscope (cc65_dbginfo handle,
 447                                             unsigned scope_id);
 448 /* Return a list of symbols in the given scope. This includes cheap local
 449  * symbols, but not symbols in subscopes. The function returns NULL if the
 450  * scope id is invalid (no such scope) and otherwise a - possibly empty -
 451  * symbol list.
 452  */
 453
 454 const cc65_symbolinfo* cc65_symbol_inrange (cc65_dbginfo handle,
 455                                             cc65_addr start, cc65_addr end);
 456 /* Return a list of labels in the given range. end is inclusive. The function
 457  * return NULL if no symbols within the given range are found. Non label
 458  * symbols are ignored and not returned.
 459  */
 460
 461 void cc65_free_symbolinfo (cc65_dbginfo Handle, const cc65_symbolinfo* Info);
 462 /* Free a symbol info record */
 463
 464
 465
 466 /*****************************************************************************/
 467 /*                                  Scopes                                   */
 468 /*****************************************************************************/
 469
 470
 471
 472 /* Scope information */
 473 typedef enum {
 474     CC65_SCOPE_GLOBAL,                  /* Global scope */
 475     CC65_SCOPE_MODULE,                  /* Module scope */
 476     CC65_SCOPE_SCOPE,                   /* .PROC/.SCOPE */
 477     CC65_SCOPE_STRUCT,                  /* .STRUCT */
 478     CC65_SCOPE_ENUM,                    /* .ENUM */
 479 } cc65_scope_type;
 480
 481 typedef struct cc65_scopedata cc65_scopedata;
 482 struct cc65_scopedata {
 483     unsigned            scope_id;       /* Id of scope */
 484     const char*         scope_name;     /* Name of scope */
 485     cc65_scope_type     scope_type;     /* Type of scope */
 486     cc65_size           scope_size;     /* Size of scope, 0 if unknown */
 487     unsigned            parent_id;      /* Id of parent scope */
 488     unsigned            symbol_id;      /* Id of scope symbol if any */
 489     unsigned            module_id;      /* Id of the module */
 490 };
 491
 492 typedef struct cc65_scopeinfo cc65_scopeinfo;
 493 struct cc65_scopeinfo {
 494     unsigned            count;          /* Number of data sets that follow */
 495     cc65_scopedata      data[1];        /* Data sets, number is dynamic */
 496 };
 497
 498
 499
 500 const cc65_scopeinfo* cc65_get_scopelist (cc65_dbginfo handle);
 501 /* Return a list of all scopes in the debug information */
 502
 503 const cc65_scopeinfo* cc65_scope_byid (cc65_dbginfo handle, unsigned id);
 504 /* Return the scope with a given id. The function returns NULL if no scope
 505  * with this id was found.
 506  */
 507
 508 const cc65_scopeinfo* cc65_scope_bymodule (cc65_dbginfo handle, unsigned module_id);
 509 /* Return the list of scopes for one module. The function returns NULL if no
 510  * scope with the given id was found.
 511  */
 512
 513 const cc65_scopeinfo* cc65_childscopes_byid (cc65_dbginfo handle, unsigned id);
 514 /* Return the direct child scopes of a scope with a given id. The function
 515  * returns NULL if no scope with this id was found, otherwise a list of the
 516  * direct childs.
 517  */
 518
 519 void cc65_free_scopeinfo (cc65_dbginfo Handle, const cc65_scopeinfo* Info);
 520 /* Free a scope info record */
 521
 522
 523
 524 /* Allow usage from C++ */
 525 #ifdef __cplusplus
 526 }
 527 #endif
 528
 529
 530
 531 /* End of dbginfo.h */
 532 #endif
 533
 534
 535