1 /*****************************************************************************/
5 /* cc65 debug info handling */
9 /* (C) 2010-2011, Ullrich von Bassewitz */
10 /* Roemerstrasse 52 */
11 /* D-70794 Filderstadt */
12 /* EMail: uz@cc65.org */
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. */
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: */
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 */
32 /*****************************************************************************/
41 /* Allow usage from C++ */
48 /*****************************************************************************/
50 /*****************************************************************************/
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.
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 */
61 /* A value that is used to mark invalid ids */
62 #define CC65_INV_ID (~0U)
66 /*****************************************************************************/
67 /* Debug info files */
68 /*****************************************************************************/
72 /* Severity for cc65_parseerror */
76 } cc65_error_severity;
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 */
88 /* Function that is called in case of parse errors */
89 typedef void (*cc65_errorfunc) (const cc65_parseerror*);
91 /* Pointer to an opaque data structure containing information from the debug
92 ** info file. Actually a handle to the data in the file.
94 typedef const void* cc65_dbginfo;
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.
106 void cc65_free_dbginfo (cc65_dbginfo Handle);
107 /* Free debug information read from a file */
111 /*****************************************************************************/
113 /*****************************************************************************/
123 /* C object storage classes */
125 CC65_CSYM_AUTO, /* Auto = on stack */
126 CC65_CSYM_REG, /* Register = in register bank */
127 CC65_CSYM_STATIC, /* Static = static storage */
128 CC65_CSYM_EXTERN /* Extern = static storage + external visibility */
131 /* C symbol information */
132 typedef struct cc65_csymdata cc65_csymdata;
133 struct cc65_csymdata {
134 unsigned csym_id; /* The internal c symbol id */
135 unsigned char csym_kind; /* Kind of c symbol */
136 unsigned char csym_sc; /* Storage class of c symbol */
137 int csym_offs; /* Offset for auto and register */
138 unsigned type_id; /* Id of the data type */
139 unsigned symbol_id; /* Attached asm symbol if any */
140 unsigned scope_id; /* Scope of c symbol */
141 const char* csym_name; /* Name of the symbol */
144 typedef struct cc65_csyminfo cc65_csyminfo;
145 struct cc65_csyminfo {
146 unsigned count; /* Number of data sets that follow */
147 cc65_csymdata data[1]; /* Data sets, number is dynamic */
152 const cc65_csyminfo* cc65_get_csymlist (cc65_dbginfo handle);
153 /* Return a list of all c symbols */
155 const cc65_csyminfo* cc65_csym_byid (cc65_dbginfo handle, unsigned id);
156 /* Return information about a c symbol with a specific id. The function
157 ** returns NULL if the id is invalid (no such c symbol) and otherwise a
158 ** cc65_csyminfo structure with one entry that contains the requested
159 ** symbol information.
162 const cc65_csyminfo* cc65_cfunc_bymodule (cc65_dbginfo handle, unsigned module_id);
163 /* Return the list of C functions (not symbols!) for a specific module. If
164 ** the module id is invalid, the function will return NULL, otherwise a
165 ** (possibly empty) c symbol list.
168 const cc65_csyminfo* cc65_cfunc_byname (cc65_dbginfo handle, const char* name);
169 /* Return a list of all C functions with the given name that have a
173 const cc65_csyminfo* cc65_csym_byscope (cc65_dbginfo handle, unsigned scope_id);
174 /* Return all C symbols for a scope. The function will return NULL if the
175 ** given id is invalid.
178 void cc65_free_csyminfo (cc65_dbginfo handle, const cc65_csyminfo* info);
179 /* Free a c symbol info record */
183 /*****************************************************************************/
185 /*****************************************************************************/
189 /* Library information */
190 typedef struct cc65_librarydata cc65_librarydata;
191 struct cc65_librarydata {
192 unsigned library_id; /* The internal library id */
193 const char* library_name; /* Name of the library */
196 typedef struct cc65_libraryinfo cc65_libraryinfo;
197 struct cc65_libraryinfo {
198 unsigned count; /* Number of data sets that follow */
199 cc65_librarydata data[1]; /* Data sets, number is dynamic */
204 const cc65_libraryinfo* cc65_get_librarylist (cc65_dbginfo handle);
205 /* Return a list of all libraries */
207 const cc65_libraryinfo* cc65_library_byid (cc65_dbginfo handle, unsigned id);
208 /* Return information about a library with a specific id. The function
209 ** returns NULL if the id is invalid (no such library) and otherwise a
210 ** cc65_libraryinfo structure with one entry that contains the requested
211 ** library information.
214 void cc65_free_libraryinfo (cc65_dbginfo handle, const cc65_libraryinfo* info);
215 /* Free a library info record */
219 /*****************************************************************************/
221 /*****************************************************************************/
227 CC65_LINE_ASM, /* Assembler source */
228 CC65_LINE_EXT, /* Externally supplied (= C) */
229 CC65_LINE_MACRO, /* Macro expansion */
232 /* Line information */
233 typedef struct cc65_linedata cc65_linedata;
234 struct cc65_linedata {
235 unsigned line_id; /* Internal id of this record */
236 unsigned source_id; /* Id of the source file */
237 cc65_line source_line; /* Line number */
238 cc65_line_type line_type; /* Type of line */
239 unsigned count; /* Nesting counter for macros */
242 typedef struct cc65_lineinfo cc65_lineinfo;
243 struct cc65_lineinfo {
244 unsigned count; /* Number of data sets that follow */
245 cc65_linedata data[1]; /* Data sets, number is dynamic */
250 const cc65_lineinfo* cc65_line_byid (cc65_dbginfo handle, unsigned id);
251 /* Return information about a line with a specific id. The function
252 ** returns NULL if the id is invalid (no such line) and otherwise a
253 ** cc65_lineinfo structure with one entry that contains the requested
254 ** module information.
257 const cc65_lineinfo* cc65_line_bynumber (cc65_dbginfo handle,
260 /* Return line information for a source file/line number combination. The
261 ** function returns NULL if no line information was found.
264 const cc65_lineinfo* cc65_line_bysource (cc65_dbginfo Handle, unsigned source_id);
265 /* Return line information for a source file. The function returns NULL if the
266 ** file id is invalid.
269 const cc65_lineinfo* cc65_line_bysymdef (cc65_dbginfo handle, unsigned symbol_id);
270 /* Return line information for the definition of a symbol. The function
271 ** returns NULL if the symbol id is invalid, otherwise a list of line infos.
274 const cc65_lineinfo* cc65_line_bysymref (cc65_dbginfo handle, unsigned symbol_id);
275 /* Return line information for all references of a symbol. The function
276 ** returns NULL if the symbol id is invalid, otherwise a list of line infos.
279 const cc65_lineinfo* cc65_line_byspan (cc65_dbginfo handle, unsigned span_id);
280 /* Return line information for a a span. The function returns NULL if the
281 ** span id is invalid, otherwise a list of line infos.
284 void cc65_free_lineinfo (cc65_dbginfo handle, const cc65_lineinfo* info);
285 /* Free line info returned by one of the other functions */
289 /*****************************************************************************/
291 /*****************************************************************************/
295 /* Module information
297 ** - scope_id contains CC65_INV_ID if the module was compiled without
298 ** debug information.
300 typedef struct cc65_moduledata cc65_moduledata;
301 struct cc65_moduledata {
302 unsigned module_id; /* The internal module id */
303 const char* module_name; /* Name of the module */
304 unsigned source_id; /* Id of the module main file */
305 unsigned library_id; /* Id of the library if any */
306 unsigned scope_id; /* Id of the main scope */
309 typedef struct cc65_moduleinfo cc65_moduleinfo;
310 struct cc65_moduleinfo {
311 unsigned count; /* Number of data sets that follow */
312 cc65_moduledata data[1]; /* Data sets, number is dynamic */
317 const cc65_moduleinfo* cc65_get_modulelist (cc65_dbginfo handle);
318 /* Return a list of all modules */
320 const cc65_moduleinfo* cc65_module_byid (cc65_dbginfo handle, unsigned id);
321 /* Return information about a module with a specific id. The function
322 ** returns NULL if the id is invalid (no such module) and otherwise a
323 ** cc65_moduleinfo structure with one entry that contains the requested
324 ** module information.
327 void cc65_free_moduleinfo (cc65_dbginfo handle, const cc65_moduleinfo* info);
328 /* Free a module info record */
332 /*****************************************************************************/
334 /*****************************************************************************/
338 /* Span information */
339 typedef struct cc65_spandata cc65_spandata;
340 struct cc65_spandata {
341 unsigned span_id; /* The internal span id */
342 cc65_addr span_start; /* Start of the span */
343 cc65_addr span_end; /* End of the span (inclusive!) */
344 unsigned segment_id; /* Id of the segment */
345 unsigned type_id; /* Id of the type of this span */
346 unsigned line_count; /* Number of lines attached */
347 unsigned scope_count; /* Number of scopes attached */
350 typedef struct cc65_spaninfo cc65_spaninfo;
351 struct cc65_spaninfo {
352 unsigned count; /* Number of data sets that follow */
353 cc65_spandata data[1]; /* Data sets, number is dynamic */
358 const cc65_spaninfo* cc65_get_spanlist (cc65_dbginfo handle);
359 /* Return a list of all spans. BEWARE: Large! */
361 const cc65_spaninfo* cc65_span_byid (cc65_dbginfo handle, unsigned id);
362 /* Return information about a span with a specific id. The function
363 ** returns NULL if the id is invalid (no such span) and otherwise a
364 ** cc65_spaninfo structure with one entry that contains the requested
368 const cc65_spaninfo* cc65_span_byaddr (cc65_dbginfo handle,
370 /* Return span information for the given address. The function returns NULL
371 ** if no spans were found for this address.
374 const cc65_spaninfo* cc65_span_byline (cc65_dbginfo handle, unsigned line_id);
375 /* Return span information for the given source line. The function returns NULL
376 ** if the line id is invalid, otherwise the spans for this line (possibly zero).
379 const cc65_spaninfo* cc65_span_byscope (cc65_dbginfo handle, unsigned scope_id);
380 /* Return span information for the given scope. The function returns NULL if
381 ** the scope id is invalid, otherwise the spans for this scope (possibly zero).
384 void cc65_free_spaninfo (cc65_dbginfo handle, const cc65_spaninfo* info);
385 /* Free a span info record */
389 /*****************************************************************************/
391 /*****************************************************************************/
395 /* Source file information */
396 typedef struct cc65_sourcedata cc65_sourcedata;
397 struct cc65_sourcedata {
398 unsigned source_id; /* The internal file id */
399 const char* source_name; /* Name of the file */
400 unsigned long source_size; /* Size of file */
401 unsigned long source_mtime; /* Modification time */
404 typedef struct cc65_sourceinfo cc65_sourceinfo;
405 struct cc65_sourceinfo {
406 unsigned count; /* Number of data sets that follow */
407 cc65_sourcedata data[1]; /* Data sets, number is dynamic */
412 const cc65_sourceinfo* cc65_get_sourcelist (cc65_dbginfo handle);
413 /* Return a list of all source files */
415 const cc65_sourceinfo* cc65_source_byid (cc65_dbginfo handle, unsigned id);
416 /* Return information about a source file with a specific id. The function
417 ** returns NULL if the id is invalid (no such source file) and otherwise a
418 ** cc65_sourceinfo structure with one entry that contains the requested
419 ** source file information.
422 const cc65_sourceinfo* cc65_source_bymodule (cc65_dbginfo handle,
424 /* Return information about the source files used to build a module. The
425 ** function returns NULL if the module id is invalid (no such module) and
426 ** otherwise a cc65_sourceinfo structure with one entry per source file.
429 void cc65_free_sourceinfo (cc65_dbginfo handle, const cc65_sourceinfo* info);
430 /* Free a source info record */
434 /*****************************************************************************/
436 /*****************************************************************************/
440 /* Scope information */
442 CC65_SCOPE_GLOBAL, /* Global scope */
443 CC65_SCOPE_MODULE, /* Module scope */
444 CC65_SCOPE_SCOPE, /* .PROC/.SCOPE */
445 CC65_SCOPE_STRUCT, /* .STRUCT */
446 CC65_SCOPE_ENUM, /* .ENUM */
449 typedef struct cc65_scopedata cc65_scopedata;
450 struct cc65_scopedata {
451 unsigned scope_id; /* Id of scope */
452 const char* scope_name; /* Name of scope */
453 cc65_scope_type scope_type; /* Type of scope */
454 cc65_size scope_size; /* Size of scope, 0 if unknown */
455 unsigned parent_id; /* Id of parent scope */
456 unsigned symbol_id; /* Id of scope symbol if any */
457 unsigned module_id; /* Id of the module */
460 typedef struct cc65_scopeinfo cc65_scopeinfo;
461 struct cc65_scopeinfo {
462 unsigned count; /* Number of data sets that follow */
463 cc65_scopedata data[1]; /* Data sets, number is dynamic */
468 const cc65_scopeinfo* cc65_get_scopelist (cc65_dbginfo handle);
469 /* Return a list of all scopes in the debug information */
471 const cc65_scopeinfo* cc65_scope_byid (cc65_dbginfo handle, unsigned id);
472 /* Return the scope with a given id. The function returns NULL if no scope
473 ** with this id was found.
476 const cc65_scopeinfo* cc65_scope_bymodule (cc65_dbginfo handle, unsigned module_id);
477 /* Return the list of scopes for one module. The function returns NULL if no
478 ** scope with the given id was found.
481 const cc65_scopeinfo* cc65_scope_byname (cc65_dbginfo handle, const char* name);
482 /* Return the list of scopes with a given name. Returns NULL if no scope with
483 ** the given name was found, otherwise a non empty scope list.
486 const cc65_scopeinfo* cc65_scope_byspan (cc65_dbginfo handle, unsigned span_id);
487 /* Return scope information for a a span. The function returns NULL if the
488 ** span id is invalid, otherwise a list of line scopes.
491 const cc65_scopeinfo* cc65_childscopes_byid (cc65_dbginfo handle, unsigned id);
492 /* Return the direct child scopes of a scope with a given id. The function
493 ** returns NULL if no scope with this id was found, otherwise a list of the
497 void cc65_free_scopeinfo (cc65_dbginfo Handle, const cc65_scopeinfo* Info);
498 /* Free a scope info record */
502 /*****************************************************************************/
504 /*****************************************************************************/
508 /* Segment information.
510 ** - output_name may be NULL if the data wasn't written to the output file
511 ** (example: bss segment)
512 ** - output_offs is invalid if there is no output_name, and may not be of
513 ** much use in case of a relocatable output file
515 typedef struct cc65_segmentdata cc65_segmentdata;
516 struct cc65_segmentdata {
517 unsigned segment_id; /* The internal segment id */
518 const char* segment_name; /* Name of the segment */
519 cc65_addr segment_start; /* Start address of segment */
520 cc65_size segment_size; /* Size of segment */
521 const char* output_name; /* Output file this seg was written to */
522 unsigned long output_offs; /* Offset of this seg in output file */
525 typedef struct cc65_segmentinfo cc65_segmentinfo;
526 struct cc65_segmentinfo {
527 unsigned count; /* Number of data sets that follow */
528 cc65_segmentdata data[1]; /* Data sets, number is dynamic */
533 const cc65_segmentinfo* cc65_get_segmentlist (cc65_dbginfo handle);
534 /* Return a list of all segments referenced in the debug information */
536 const cc65_segmentinfo* cc65_segment_byid (cc65_dbginfo handle, unsigned id);
537 /* Return information about a segment with a specific id. The function returns
538 ** NULL if the id is invalid (no such segment) and otherwise a cc65_segmentinfo
539 ** structure with one entry that contains the requested segment information.
542 const cc65_segmentinfo* cc65_segment_byname (cc65_dbginfo handle,
544 /* Return information about a segment with a specific name. The function
545 ** returns NULL if no segment with this name exists and otherwise a
546 ** cc65_segmentinfo structure with one entry that contains the requested
550 void cc65_free_segmentinfo (cc65_dbginfo handle, const cc65_segmentinfo* info);
551 /* Free a segment info record */
555 /*****************************************************************************/
557 /*****************************************************************************/
561 /* Symbol information */
564 CC65_SYM_LABEL, /* Some sort of address */
565 CC65_SYM_IMPORT, /* An import */
569 ** - If the symbol is segment relative, the segment id gives segment
570 ** information, otherwise it contains CC65_INV_ID.
571 ** - If the type is CC65_SYM_IMPORT, export_id may contain the id of the
572 ** export. This is not the case if the module contaiing the export doesn't
573 ** have debug information.
574 ** - For an import, the fields symbol_value and segment_id are taken from
575 ** the export, if it is available, since imports have no value or segments
577 ** - For an import symbol_size doesn't have a meaning.
578 ** - For normal symbols (not cheap locals) parent_id contains CC65_INV_ID,
579 ** for cheap locals it contains the symbol id of the parent symbol.
581 typedef struct cc65_symboldata cc65_symboldata;
582 struct cc65_symboldata {
583 unsigned symbol_id; /* Id of symbol */
584 const char* symbol_name; /* Name of symbol */
585 cc65_symbol_type symbol_type; /* Type of symbol */
586 cc65_size symbol_size; /* Size of symbol, 0 if unknown */
587 long symbol_value; /* Value of symbol */
588 unsigned export_id; /* For imports: Matching export */
589 unsigned segment_id; /* Id of segment if any */
590 unsigned scope_id; /* The scope this symbol is in */
591 unsigned parent_id; /* Parent symbol for cheap locals */
594 typedef struct cc65_symbolinfo cc65_symbolinfo;
595 struct cc65_symbolinfo {
596 unsigned count; /* Number of data sets that follow */
597 cc65_symboldata data[1]; /* Data sets, number is dynamic */
602 const cc65_symbolinfo* cc65_symbol_byid (cc65_dbginfo handle, unsigned id);
603 /* Return the symbol with a given id. The function returns NULL if no symbol
604 ** with this id was found.
607 const cc65_symbolinfo* cc65_symbol_byname (cc65_dbginfo handle, const char* name);
608 /* Return a list of symbols with a given name. The function returns NULL if
609 ** no symbol with this name was found.
612 const cc65_symbolinfo* cc65_symbol_byscope (cc65_dbginfo handle,
614 /* Return a list of symbols in the given scope. This includes cheap local
615 ** symbols, but not symbols in subscopes. The function returns NULL if the
616 ** scope id is invalid (no such scope) and otherwise a - possibly empty -
620 const cc65_symbolinfo* cc65_symbol_inrange (cc65_dbginfo handle,
621 cc65_addr start, cc65_addr end);
622 /* Return a list of labels in the given range. end is inclusive. The function
623 ** return NULL if no symbols within the given range are found. Non label
624 ** symbols are ignored and not returned.
627 void cc65_free_symbolinfo (cc65_dbginfo handle, const cc65_symbolinfo* info);
628 /* Free a symbol info record */
632 /*****************************************************************************/
634 /*****************************************************************************/
638 /* Type information */
649 /* The following ones are currently unavailable: */
656 /* A type is a linked list of typedata structures. In case of arrays, the
657 ** structure will contain an element count and the element type. In case of
658 ** pointers, the structure will contain the type of the data, the pointer
659 ** points to (currently, there are only VOID pointers).
660 ** The next pointer points to the next entry in the list. It is NULL if the
661 ** end of the list is reached.
663 typedef struct cc65_typedata cc65_typedata;
664 struct cc65_typedata {
665 cc65_typedata* next; /* Pointer to next entry */
666 cc65_typetoken what; /* What kind of type is it? */
667 cc65_size size; /* The size of the data */
669 /* Depending on "what", one of the members of this union follows */
672 /* In case of CC65_TYPE_PTR or CC65_TYPE_FARPTR */
674 const cc65_typedata* ind_type; /* Type the pointer points to */
677 /* In case of CC65_TYPE_ARRAY */
679 cc65_size ele_count; /* Element count */
680 const cc65_typedata* ele_type; /* Element type */
688 const cc65_typedata* cc65_type_byid (cc65_dbginfo handle, unsigned id);
689 /* Return the data for the type with the given id. The function returns NULL
690 ** if no type with this id was found.
693 void cc65_free_typedata (cc65_dbginfo Handle, const cc65_typedata* data);
694 /* Free a symbol info record */
698 /* Allow usage from C++ */
705 /* End of dbginfo.h */