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 /* A structure that is used to store a list of ids */
  65 typedef struct cc65_idlist cc65_idlist;
  66 struct cc65_idlist {
  67     unsigned            count;          /* Number of elements */
  68     unsigned*           ids;            /* List of ids, number is dynamic */
  69 };
  70
  71
  72
  73 /*****************************************************************************/
  74 /*                             Debug info files                              */
  75 /*****************************************************************************/
  76
  77
  78
  79 /* Severity for cc65_parseerror */
  80 typedef enum {
  81     CC65_WARNING,
  82     CC65_ERROR,
  83 } cc65_error_severity;
  84
  85 /* Warnings/errors in cc65_read_dbginfo are passed via this struct */
  86 typedef struct cc65_parseerror cc65_parseerror;
  87 struct cc65_parseerror {
  88     cc65_error_severity type;           /* Type of error */
  89     const char*         name;           /* Name of input file */
  90     cc65_line           line;           /* Error line */
  91     unsigned            column;         /* Error column */
  92     char                errormsg[1];    /* Error message */
  93 };
  94
  95 /* Function that is called in case of parse errors */
  96 typedef void (*cc65_errorfunc) (const struct cc65_parseerror*);
  97
  98 /* Pointer to an opaque data structure containing information from the debug
  99  * info file. Actually a handle to the data in the file.
 100  */
 101 typedef const void* cc65_dbginfo;
 102
 103
 104
 105 cc65_dbginfo cc65_read_dbginfo (const char* filename, cc65_errorfunc errorfunc);
 106 /* Parse the debug info file with the given name. On success, the function
 107  * will return a pointer to an opaque cc65_dbginfo structure, that must be
 108  * passed to the other functions in this module to retrieve information.
 109  * errorfunc is called in case of warnings and errors. If the file cannot be
 110  * read successfully, NULL is returned.
 111  */
 112
 113 void cc65_free_dbginfo (cc65_dbginfo Handle);
 114 /* Free debug information read from a file */
 115
 116
 117
 118 /*****************************************************************************/
 119 /*                                 Libraries                                 */
 120 /*****************************************************************************/
 121
 122
 123
 124 /* Library information */
 125 typedef struct cc65_librarydata cc65_librarydata;
 126 struct cc65_librarydata {
 127     unsigned            library_id;     /* The internal library id */
 128     const char*         library_name;   /* Name of the library */
 129 };
 130
 131 typedef struct cc65_libraryinfo cc65_libraryinfo;
 132 struct cc65_libraryinfo {
 133     unsigned            count;          /* Number of data sets that follow */
 134     cc65_librarydata    data[1];        /* Data sets, number is dynamic */
 135 };
 136
 137
 138
 139 const cc65_libraryinfo* cc65_get_librarylist (cc65_dbginfo handle);
 140 /* Return a list of all libraries */
 141
 142 const cc65_libraryinfo* cc65_libraryinfo_byid (cc65_dbginfo handle, unsigned id);
 143 /* Return information about a library with a specific id. The function
 144  * returns NULL if the id is invalid (no such library) and otherwise a
 145  * cc65_libraryinfo structure with one entry that contains the requested
 146  * library information.
 147  */
 148
 149 void cc65_free_libraryinfo (cc65_dbginfo handle, const cc65_libraryinfo* info);
 150 /* Free a library info record */
 151
 152
 153
 154 /*****************************************************************************/
 155 /*                                 Line info                                 */
 156 /*****************************************************************************/
 157
 158
 159
 160 /* Type of line */
 161 typedef enum {
 162     CC65_LINE_ASM,                      /* Assembler source */
 163     CC65_LINE_EXT,                      /* Externally supplied (= C) */
 164     CC65_LINE_MACRO,                    /* Macro expansion */
 165 } cc65_line_type;
 166
 167 /* Line information */
 168 typedef struct cc65_linedata cc65_linedata;
 169 struct cc65_linedata {
 170     unsigned            line_id;        /* Internal id of this record */
 171     unsigned            source_id;      /* Id of the source file */
 172     cc65_line           source_line;    /* Line number */
 173     cc65_line_type      line_type;      /* Type of line */
 174     unsigned            count;          /* Nesting counter for macros */
 175     cc65_idlist         span_list;      /* List of spans for this line */
 176 };
 177
 178 typedef struct cc65_lineinfo cc65_lineinfo;
 179 struct cc65_lineinfo {
 180     unsigned            count;          /* Number of data sets that follow */
 181     cc65_linedata       data[1];        /* Data sets, number is dynamic */
 182 };
 183
 184
 185
 186 const cc65_lineinfo* cc65_lineinfo_byline (cc65_dbginfo handle,
 187                                            unsigned source_id,
 188                                            cc65_line line);
 189 /* Return line information for a source file/line number combination. The
 190  * function returns NULL if no line information was found.
 191  */
 192
 193 void cc65_free_lineinfo (cc65_dbginfo handle, const cc65_lineinfo* info);
 194 /* Free line info returned by one of the other functions */
 195
 196
 197
 198 /*****************************************************************************/
 199 /*                                  Modules                                  */
 200 /*****************************************************************************/
 201
 202
 203
 204 /* Module information */
 205 typedef struct cc65_moduledata cc65_moduledata;
 206 struct cc65_moduledata {
 207     unsigned            module_id;      /* The internal module id */
 208     const char*         module_name;    /* Name of the module */
 209     unsigned            source_id;      /* Id of the module main file */
 210     unsigned            library_id;     /* Id of the library if any */
 211     unsigned            scope_id;       /* Id of the main scope */
 212 };
 213
 214 typedef struct cc65_moduleinfo cc65_moduleinfo;
 215 struct cc65_moduleinfo {
 216     unsigned            count;          /* Number of data sets that follow */
 217     cc65_moduledata     data[1];        /* Data sets, number is dynamic */
 218 };
 219
 220
 221
 222 const cc65_moduleinfo* cc65_get_modulelist (cc65_dbginfo handle);
 223 /* Return a list of all modules */
 224
 225 const cc65_moduleinfo* cc65_moduleinfo_byid (cc65_dbginfo handle, unsigned id);
 226 /* Return information about a module with a specific id. The function
 227  * returns NULL if the id is invalid (no such module) and otherwise a
 228  * cc65_moduleinfo structure with one entry that contains the requested
 229  * module information.
 230  */
 231
 232 void cc65_free_moduleinfo (cc65_dbginfo handle, const cc65_moduleinfo* info);
 233 /* Free a module info record */
 234
 235
 236
 237 /*****************************************************************************/
 238 /*                                   Spans                                   */
 239 /*****************************************************************************/
 240
 241
 242
 243 /* Span information */
 244 typedef struct cc65_spandata cc65_spandata;
 245 struct cc65_spandata {
 246     unsigned            span_id;        /* The internal span id */
 247     cc65_addr           span_start;     /* Start of the span */
 248     cc65_addr           span_end;       /* End of the span (inclusive!) */
 249     unsigned            segment_id;     /* Id of the segment */
 250 };
 251
 252 typedef struct cc65_spaninfo cc65_spaninfo;
 253 struct cc65_spaninfo {
 254     unsigned            count;          /* Number of data sets that follow */
 255     cc65_spandata       data[1];        /* Data sets, number is dynamic */
 256 };
 257
 258
 259
 260 const cc65_spaninfo* cc65_get_spanlist (cc65_dbginfo handle);
 261 /* Return a list of all spans. BEWARE: Large! */
 262
 263 const cc65_spaninfo* cc65_spaninfo_byid (cc65_dbginfo handle, unsigned id);
 264 /* Return information about a span with a specific id. The function
 265  * returns NULL if the id is invalid (no such span) and otherwise a
 266  * cc65_spaninfo structure with one entry that contains the requested
 267  * span information.
 268  */
 269
 270 const cc65_spaninfo* cc65_spaninfo_byaddr (cc65_dbginfo handle,
 271                                            unsigned long addr);
 272 /* Return span information for the given address. The function returns NULL
 273  * if no spans were found for this address.
 274  */
 275
 276 void cc65_free_spaninfo (cc65_dbginfo handle, const cc65_spaninfo* info);
 277 /* Free a span info record */
 278
 279
 280
 281 /*****************************************************************************/
 282 /*                               Source files                                */
 283 /*****************************************************************************/
 284
 285
 286
 287 /* Source file information */
 288 typedef struct cc65_sourcedata cc65_sourcedata;
 289 struct cc65_sourcedata {
 290     unsigned            source_id;      /* The internal file id */
 291     const char*         source_name;    /* Name of the file */
 292     unsigned long       source_size;    /* Size of file */
 293     unsigned long       source_mtime;   /* Modification time */
 294 };
 295
 296 typedef struct cc65_sourceinfo cc65_sourceinfo;
 297 struct cc65_sourceinfo {
 298     unsigned            count;          /* Number of data sets that follow */
 299     cc65_sourcedata     data[1];        /* Data sets, number is dynamic */
 300 };
 301
 302
 303
 304 const cc65_sourceinfo* cc65_get_sourcelist (cc65_dbginfo handle);
 305 /* Return a list of all source files */
 306
 307 const cc65_sourceinfo* cc65_sourceinfo_byid (cc65_dbginfo handle, unsigned id);
 308 /* Return information about a source file with a specific id. The function
 309  * returns NULL if the id is invalid (no such source file) and otherwise a
 310  * cc65_sourceinfo structure with one entry that contains the requested
 311  * source file information.
 312  */
 313
 314 const cc65_sourceinfo* cc65_sourceinfo_bymodule (cc65_dbginfo handle,
 315                                                  unsigned module_id);
 316 /* Return information about the source files used to build a module. The
 317  * function returns NULL if the module id is invalid (no such module) and
 318  * otherwise a cc65_sourceinfo structure with one entry per source file.
 319  */
 320
 321 void cc65_free_sourceinfo (cc65_dbginfo handle, const cc65_sourceinfo* info);
 322 /* Free a source info record */
 323
 324
 325
 326 /*****************************************************************************/
 327 /*                                 Segments                                  */
 328 /*****************************************************************************/
 329
 330
 331
 332 /* Segment information.
 333  * Notes:
 334  *   - output_name may be NULL if the data wasn't written to the output file
 335  *     (example: bss segment)
 336  *   - output_offs is invalid if there is no output_name, and may not be of
 337  *     much use in case of a relocatable output file
 338  */
 339 typedef struct cc65_segmentdata cc65_segmentdata;
 340 struct cc65_segmentdata {
 341     unsigned            segment_id;     /* The internal segment id */
 342     const char*         segment_name;   /* Name of the segment */
 343     cc65_addr           segment_start;  /* Start address of segment */
 344     cc65_size           segment_size;   /* Size of segment */
 345     const char*         output_name;    /* Output file this seg was written to */
 346     unsigned long       output_offs;    /* Offset of this seg in output file */
 347 };
 348
 349 typedef struct cc65_segmentinfo cc65_segmentinfo;
 350 struct cc65_segmentinfo {
 351     unsigned            count;          /* Number of data sets that follow */
 352     cc65_segmentdata    data[1];        /* Data sets, number is dynamic */
 353 };
 354
 355
 356
 357 const cc65_segmentinfo* cc65_get_segmentlist (cc65_dbginfo handle);
 358 /* Return a list of all segments referenced in the debug information */
 359
 360 const cc65_segmentinfo* cc65_segmentinfo_byid (cc65_dbginfo handle, unsigned id);
 361 /* Return information about a segment with a specific id. The function returns
 362  * NULL if the id is invalid (no such segment) and otherwise a cc65_segmentinfo
 363  * structure with one entry that contains the requested segment information.
 364  */
 365
 366 void cc65_free_segmentinfo (cc65_dbginfo handle, const cc65_segmentinfo* info);
 367 /* Free a segment info record */
 368
 369
 370
 371 /*****************************************************************************/
 372 /*                                  Symbols                                  */
 373 /*****************************************************************************/
 374
 375
 376
 377 /* Symbol information */
 378 typedef enum {
 379     CC65_SYM_EQUATE,
 380     CC65_SYM_LABEL,                     /* Some sort of address */
 381 } cc65_symbol_type;
 382
 383 typedef struct cc65_symboldata cc65_symboldata;
 384 struct cc65_symboldata {
 385     unsigned            symbol_id;      /* Id of symbol */
 386     const char*         symbol_name;    /* Name of symbol */
 387     cc65_symbol_type    symbol_type;    /* Type of symbol */
 388     cc65_size           symbol_size;    /* Size of symbol, 0 if unknown */
 389     long                symbol_value;   /* Value of symbol */
 390     unsigned            segment_id;     /* If the symbol is segment relative,
 391                                          * this contains the id of segment,
 392                                          * otherwise CC65_INV_ID
 393                                          */
 394     unsigned            scope_id;       /* The scope this symbol is in */
 395     unsigned            parent_id;      /* Parent symbol for cheap locals */
 396 };
 397
 398 typedef struct cc65_symbolinfo cc65_symbolinfo;
 399 struct cc65_symbolinfo {
 400     unsigned            count;          /* Number of data sets that follow */
 401     cc65_symboldata     data[1];        /* Data sets, number is dynamic */
 402 };
 403
 404
 405
 406 const cc65_symbolinfo* cc65_symbol_byid (cc65_dbginfo handle, unsigned id);
 407 /* Return the symbol with a given id. The function returns NULL if no symbol
 408  * with this id was found.
 409  */
 410
 411 const cc65_symbolinfo* cc65_symbol_byname (cc65_dbginfo handle, const char* name);
 412 /* Return a list of symbols with a given name. The function returns NULL if
 413  * no symbol with this name was found.
 414  */
 415
 416 const cc65_symbolinfo* cc65_symbol_inrange (cc65_dbginfo handle,
 417                                             cc65_addr start, cc65_addr end);
 418 /* Return a list of labels in the given range. end is inclusive. The function
 419  * return NULL if no symbols within the given range are found. Non label
 420  * symbols are ignored and not returned.
 421  */
 422
 423 void cc65_free_symbolinfo (cc65_dbginfo Handle, const cc65_symbolinfo* Info);
 424 /* Free a symbol info record */
 425
 426
 427
 428 /*****************************************************************************/
 429 /*                                  Scopes                                   */
 430 /*****************************************************************************/
 431
 432
 433
 434 /* Scope information */
 435 typedef enum {
 436     CC65_SCOPE_GLOBAL,                  /* Global scope */
 437     CC65_SCOPE_MODULE,                  /* Module scope */
 438     CC65_SCOPE_SCOPE,                   /* .PROC/.SCOPE */
 439     CC65_SCOPE_STRUCT,                  /* .STRUCT */
 440     CC65_SCOPE_ENUM,                    /* .ENUM */
 441 } cc65_scope_type;
 442
 443 typedef struct cc65_scopedata cc65_scopedata;
 444 struct cc65_scopedata {
 445     unsigned            scope_id;       /* Id of scope */
 446     const char*         scope_name;     /* Name of scope */
 447     cc65_scope_type     scope_type;     /* Type of scope */
 448     cc65_size           scope_size;     /* Size of scope, 0 if unknown */
 449     unsigned            scope_parent;   /* Id of parent scope */
 450     unsigned            symbol_id;      /* Id of scope symbol if any */
 451     unsigned            module_id;      /* Id of the module */
 452 };
 453
 454 typedef struct cc65_scopeinfo cc65_scopeinfo;
 455 struct cc65_scopeinfo {
 456     unsigned            count;          /* Number of data sets that follow */
 457     cc65_scopedata      data[1];        /* Data sets, number is dynamic */
 458 };
 459
 460
 461
 462 const cc65_scopeinfo* cc65_scope_byid (cc65_dbginfo handle, unsigned id);
 463 /* Return the scope with a given id. The function returns NULL if no scope
 464  * with this id was found.
 465  */
 466
 467 const cc65_scopeinfo* cc65_scope_bymodule (cc65_dbginfo handle, unsigned module_id);
 468 /* Return the list of scopes for one module. The function returns NULL if no
 469  * scope with the given id was found.
 470  */
 471
 472 void cc65_free_scopeinfo (cc65_dbginfo Handle, const cc65_scopeinfo* Info);
 473 /* Free a scope info record */
 474
 475
 476
 477 /* Allow usage from C++ */
 478 #ifdef __cplusplus
 479 }
 480 #endif
 481
 482
 483
 484 /* End of dbginfo.h */
 485 #endif
 486
 487
 488