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 /*****************************************************************************/
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 */
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 */
132 const cc65_libraryinfo* cc65_get_librarylist (cc65_dbginfo handle);
133 /* Return a list of all libraries */
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.
142 void cc65_free_libraryinfo (cc65_dbginfo handle, const cc65_libraryinfo* info);
143 /* Free a library info record */
147 /*****************************************************************************/
149 /*****************************************************************************/
155 CC65_LINE_ASM, /* Assembler source */
156 CC65_LINE_EXT, /* Externally supplied (= C) */
157 CC65_LINE_MACRO, /* Macro expansion */
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 */
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 */
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.
185 const cc65_lineinfo* cc65_line_bynumber (cc65_dbginfo handle,
188 /* Return line information for a source file/line number combination. The
189 * function returns NULL if no line information was found.
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.
197 void cc65_free_lineinfo (cc65_dbginfo handle, const cc65_lineinfo* info);
198 /* Free line info returned by one of the other functions */
202 /*****************************************************************************/
204 /*****************************************************************************/
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 */
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 */
226 const cc65_moduleinfo* cc65_get_modulelist (cc65_dbginfo handle);
227 /* Return a list of all modules */
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.
236 void cc65_free_moduleinfo (cc65_dbginfo handle, const cc65_moduleinfo* info);
237 /* Free a module info record */
241 /*****************************************************************************/
243 /*****************************************************************************/
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 */
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 */
264 const cc65_spaninfo* cc65_get_spanlist (cc65_dbginfo handle);
265 /* Return a list of all spans. BEWARE: Large! */
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
274 const cc65_spaninfo* cc65_span_byaddr (cc65_dbginfo handle,
276 /* Return span information for the given address. The function returns NULL
277 * if no spans were found for this address.
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).
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).
290 void cc65_free_spaninfo (cc65_dbginfo handle, const cc65_spaninfo* info);
291 /* Free a span info record */
295 /*****************************************************************************/
297 /*****************************************************************************/
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 */
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 */
318 const cc65_sourceinfo* cc65_get_sourcelist (cc65_dbginfo handle);
319 /* Return a list of all source files */
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.
328 const cc65_sourceinfo* cc65_source_bymodule (cc65_dbginfo handle,
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.
335 void cc65_free_sourceinfo (cc65_dbginfo handle, const cc65_sourceinfo* info);
336 /* Free a source info record */
340 /*****************************************************************************/
342 /*****************************************************************************/
346 /* Segment information.
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
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 */
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 */
371 const cc65_segmentinfo* cc65_get_segmentlist (cc65_dbginfo handle);
372 /* Return a list of all segments referenced in the debug information */
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.
380 const cc65_segmentinfo* cc65_segment_byname (cc65_dbginfo handle,
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
388 void cc65_free_segmentinfo (cc65_dbginfo handle, const cc65_segmentinfo* info);
389 /* Free a segment info record */
393 /*****************************************************************************/
395 /*****************************************************************************/
399 /* Symbol information */
402 CC65_SYM_LABEL, /* Some sort of address */
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.
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 */
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 */
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.
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.
446 const cc65_symbolinfo* cc65_symbol_inrange (cc65_dbginfo handle,
447 cc65_addr start, cc65_addr end);
448 /* Return a list of labels in the given range. end is inclusive. The function
449 * return NULL if no symbols within the given range are found. Non label
450 * symbols are ignored and not returned.
453 void cc65_free_symbolinfo (cc65_dbginfo Handle, const cc65_symbolinfo* Info);
454 /* Free a symbol info record */
458 /*****************************************************************************/
460 /*****************************************************************************/
464 /* Scope information */
466 CC65_SCOPE_GLOBAL, /* Global scope */
467 CC65_SCOPE_MODULE, /* Module scope */
468 CC65_SCOPE_SCOPE, /* .PROC/.SCOPE */
469 CC65_SCOPE_STRUCT, /* .STRUCT */
470 CC65_SCOPE_ENUM, /* .ENUM */
473 typedef struct cc65_scopedata cc65_scopedata;
474 struct cc65_scopedata {
475 unsigned scope_id; /* Id of scope */
476 const char* scope_name; /* Name of scope */
477 cc65_scope_type scope_type; /* Type of scope */
478 cc65_size scope_size; /* Size of scope, 0 if unknown */
479 unsigned parent_id; /* Id of parent scope */
480 unsigned symbol_id; /* Id of scope symbol if any */
481 unsigned module_id; /* Id of the module */
484 typedef struct cc65_scopeinfo cc65_scopeinfo;
485 struct cc65_scopeinfo {
486 unsigned count; /* Number of data sets that follow */
487 cc65_scopedata data[1]; /* Data sets, number is dynamic */
492 const cc65_scopeinfo* cc65_get_scopelist (cc65_dbginfo handle);
493 /* Return a list of all scopes in the debug information */
495 const cc65_scopeinfo* cc65_scope_byid (cc65_dbginfo handle, unsigned id);
496 /* Return the scope with a given id. The function returns NULL if no scope
497 * with this id was found.
500 const cc65_scopeinfo* cc65_scope_bymodule (cc65_dbginfo handle, unsigned module_id);
501 /* Return the list of scopes for one module. The function returns NULL if no
502 * scope with the given id was found.
505 void cc65_free_scopeinfo (cc65_dbginfo Handle, const cc65_scopeinfo* Info);
506 /* Free a scope info record */
510 /* Allow usage from C++ */
517 /* End of dbginfo.h */