]> git.sur5r.net Git - cc65/blob - src/dbginfo/dbginfo.h
Pointers passed outside the module should be const.
[cc65] / 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 const cc65_lineinfo* cc65_line_bysymdef (cc65_dbginfo handle, unsigned symbol_id);
198 /* Return line information for the definition of a symbol. The function
199  * returns NULL if the symbol id is invalid, otherwise a list of line infos.
200  */
201
202 const cc65_lineinfo* cc65_line_bysymref (cc65_dbginfo handle, unsigned symbol_id);
203 /* Return line information for all references of a symbol. The function
204  * returns NULL if the symbol id is invalid, otherwise a list of line infos.
205  */
206
207 const cc65_lineinfo* cc65_line_byspan (cc65_dbginfo handle, unsigned span_id);
208 /* Return line information for a a span. The function returns NULL if the
209  * span id is invalid, otherwise a list of line infos.
210  */
211
212 void cc65_free_lineinfo (cc65_dbginfo handle, const cc65_lineinfo* info);
213 /* Free line info returned by one of the other functions */
214
215
216
217 /*****************************************************************************/
218 /*                                  Modules                                  */
219 /*****************************************************************************/
220
221
222
223 /* Module information
224  * Notes:
225  *   - scope_id contains CC65_INV_ID if the module was compiled without
226  *     debug information.
227  */
228 typedef struct cc65_moduledata cc65_moduledata;
229 struct cc65_moduledata {
230     unsigned            module_id;      /* The internal module id */
231     const char*         module_name;    /* Name of the module */
232     unsigned            source_id;      /* Id of the module main file */
233     unsigned            library_id;     /* Id of the library if any */
234     unsigned            scope_id;       /* Id of the main scope */
235 };
236
237 typedef struct cc65_moduleinfo cc65_moduleinfo;
238 struct cc65_moduleinfo {
239     unsigned            count;          /* Number of data sets that follow */
240     cc65_moduledata     data[1];        /* Data sets, number is dynamic */
241 };
242
243
244
245 const cc65_moduleinfo* cc65_get_modulelist (cc65_dbginfo handle);
246 /* Return a list of all modules */
247
248 const cc65_moduleinfo* cc65_module_byid (cc65_dbginfo handle, unsigned id);
249 /* Return information about a module with a specific id. The function
250  * returns NULL if the id is invalid (no such module) and otherwise a
251  * cc65_moduleinfo structure with one entry that contains the requested
252  * module information.
253  */
254
255 void cc65_free_moduleinfo (cc65_dbginfo handle, const cc65_moduleinfo* info);
256 /* Free a module info record */
257
258
259
260 /*****************************************************************************/
261 /*                                   Spans                                   */
262 /*****************************************************************************/
263
264
265
266 /* Span information */
267 typedef struct cc65_spandata cc65_spandata;
268 struct cc65_spandata {
269     unsigned            span_id;        /* The internal span id */
270     cc65_addr           span_start;     /* Start of the span */
271     cc65_addr           span_end;       /* End of the span (inclusive!) */
272     unsigned            segment_id;     /* Id of the segment */
273     unsigned            type_id;        /* Id of the type of this span */
274     unsigned            line_count;     /* Number of lines attached */
275     unsigned            scope_count;    /* Number of scopes attached */
276 };
277
278 typedef struct cc65_spaninfo cc65_spaninfo;
279 struct cc65_spaninfo {
280     unsigned            count;          /* Number of data sets that follow */
281     cc65_spandata       data[1];        /* Data sets, number is dynamic */
282 };
283
284
285
286 const cc65_spaninfo* cc65_get_spanlist (cc65_dbginfo handle);
287 /* Return a list of all spans. BEWARE: Large! */
288
289 const cc65_spaninfo* cc65_span_byid (cc65_dbginfo handle, unsigned id);
290 /* Return information about a span with a specific id. The function
291  * returns NULL if the id is invalid (no such span) and otherwise a
292  * cc65_spaninfo structure with one entry that contains the requested
293  * span information.
294  */
295
296 const cc65_spaninfo* cc65_span_byaddr (cc65_dbginfo handle,
297                                        unsigned long addr);
298 /* Return span information for the given address. The function returns NULL
299  * if no spans were found for this address.
300  */
301
302 const cc65_spaninfo* cc65_span_byline (cc65_dbginfo handle, unsigned line_id);
303 /* Return span information for the given source line. The function returns NULL
304  * if the line id is invalid, otherwise the spans for this line (possibly zero).
305  */
306
307 const cc65_spaninfo* cc65_span_byscope (cc65_dbginfo handle, unsigned scope_id);
308 /* Return span information for the given scope. The function returns NULL if
309  * the scope id is invalid, otherwise the spans for this scope (possibly zero).
310  */
311
312 void cc65_free_spaninfo (cc65_dbginfo handle, const cc65_spaninfo* info);
313 /* Free a span info record */
314
315
316
317 /*****************************************************************************/
318 /*                               Source files                                */
319 /*****************************************************************************/
320
321
322
323 /* Source file information */
324 typedef struct cc65_sourcedata cc65_sourcedata;
325 struct cc65_sourcedata {
326     unsigned            source_id;      /* The internal file id */
327     const char*         source_name;    /* Name of the file */
328     unsigned long       source_size;    /* Size of file */
329     unsigned long       source_mtime;   /* Modification time */
330 };
331
332 typedef struct cc65_sourceinfo cc65_sourceinfo;
333 struct cc65_sourceinfo {
334     unsigned            count;          /* Number of data sets that follow */
335     cc65_sourcedata     data[1];        /* Data sets, number is dynamic */
336 };
337
338
339
340 const cc65_sourceinfo* cc65_get_sourcelist (cc65_dbginfo handle);
341 /* Return a list of all source files */
342
343 const cc65_sourceinfo* cc65_source_byid (cc65_dbginfo handle, unsigned id);
344 /* Return information about a source file with a specific id. The function
345  * returns NULL if the id is invalid (no such source file) and otherwise a
346  * cc65_sourceinfo structure with one entry that contains the requested
347  * source file information.
348  */
349
350 const cc65_sourceinfo* cc65_source_bymodule (cc65_dbginfo handle,
351                                              unsigned module_id);
352 /* Return information about the source files used to build a module. The
353  * function returns NULL if the module id is invalid (no such module) and
354  * otherwise a cc65_sourceinfo structure with one entry per source file.
355  */
356
357 void cc65_free_sourceinfo (cc65_dbginfo handle, const cc65_sourceinfo* info);
358 /* Free a source info record */
359
360
361
362 /*****************************************************************************/
363 /*                                  Scopes                                   */
364 /*****************************************************************************/
365
366
367
368 /* Scope information */
369 typedef enum {
370     CC65_SCOPE_GLOBAL,                  /* Global scope */
371     CC65_SCOPE_MODULE,                  /* Module scope */
372     CC65_SCOPE_SCOPE,                   /* .PROC/.SCOPE */
373     CC65_SCOPE_STRUCT,                  /* .STRUCT */
374     CC65_SCOPE_ENUM,                    /* .ENUM */
375 } cc65_scope_type;
376
377 typedef struct cc65_scopedata cc65_scopedata;
378 struct cc65_scopedata {
379     unsigned            scope_id;       /* Id of scope */
380     const char*         scope_name;     /* Name of scope */
381     cc65_scope_type     scope_type;     /* Type of scope */
382     cc65_size           scope_size;     /* Size of scope, 0 if unknown */
383     unsigned            parent_id;      /* Id of parent scope */
384     unsigned            symbol_id;      /* Id of scope symbol if any */
385     unsigned            module_id;      /* Id of the module */
386 };
387
388 typedef struct cc65_scopeinfo cc65_scopeinfo;
389 struct cc65_scopeinfo {
390     unsigned            count;          /* Number of data sets that follow */
391     cc65_scopedata      data[1];        /* Data sets, number is dynamic */
392 };
393
394
395
396 const cc65_scopeinfo* cc65_get_scopelist (cc65_dbginfo handle);
397 /* Return a list of all scopes in the debug information */
398
399 const cc65_scopeinfo* cc65_scope_byid (cc65_dbginfo handle, unsigned id);
400 /* Return the scope with a given id. The function returns NULL if no scope
401  * with this id was found.
402  */
403
404 const cc65_scopeinfo* cc65_scope_bymodule (cc65_dbginfo handle, unsigned module_id);
405 /* Return the list of scopes for one module. The function returns NULL if no
406  * scope with the given id was found.
407  */
408
409 const cc65_scopeinfo* cc65_scope_byname (cc65_dbginfo handle, const char* name);
410 /* Return the list of scopes with a given name. Returns NULL if no scope with
411  * the given name was found, otherwise a non empty scope list.
412  */
413
414 const cc65_scopeinfo* cc65_scope_byspan (cc65_dbginfo handle, unsigned span_id);
415 /* Return scope information for a a span. The function returns NULL if the
416  * span id is invalid, otherwise a list of line scopes.
417  */
418
419 const cc65_scopeinfo* cc65_childscopes_byid (cc65_dbginfo handle, unsigned id);
420 /* Return the direct child scopes of a scope with a given id. The function
421  * returns NULL if no scope with this id was found, otherwise a list of the
422  * direct childs.
423  */
424
425 void cc65_free_scopeinfo (cc65_dbginfo Handle, const cc65_scopeinfo* Info);
426 /* Free a scope info record */
427
428
429
430 /*****************************************************************************/
431 /*                                 Segments                                  */
432 /*****************************************************************************/
433
434
435
436 /* Segment information.
437  * Notes:
438  *   - output_name may be NULL if the data wasn't written to the output file
439  *     (example: bss segment)
440  *   - output_offs is invalid if there is no output_name, and may not be of
441  *     much use in case of a relocatable output file
442  */
443 typedef struct cc65_segmentdata cc65_segmentdata;
444 struct cc65_segmentdata {
445     unsigned            segment_id;     /* The internal segment id */
446     const char*         segment_name;   /* Name of the segment */
447     cc65_addr           segment_start;  /* Start address of segment */
448     cc65_size           segment_size;   /* Size of segment */
449     const char*         output_name;    /* Output file this seg was written to */
450     unsigned long       output_offs;    /* Offset of this seg in output file */
451 };
452
453 typedef struct cc65_segmentinfo cc65_segmentinfo;
454 struct cc65_segmentinfo {
455     unsigned            count;          /* Number of data sets that follow */
456     cc65_segmentdata    data[1];        /* Data sets, number is dynamic */
457 };
458
459
460
461 const cc65_segmentinfo* cc65_get_segmentlist (cc65_dbginfo handle);
462 /* Return a list of all segments referenced in the debug information */
463
464 const cc65_segmentinfo* cc65_segment_byid (cc65_dbginfo handle, unsigned id);
465 /* Return information about a segment with a specific id. The function returns
466  * NULL if the id is invalid (no such segment) and otherwise a cc65_segmentinfo
467  * structure with one entry that contains the requested segment information.
468  */
469
470 const cc65_segmentinfo* cc65_segment_byname (cc65_dbginfo handle,
471                                              const char* name);
472 /* Return information about a segment with a specific name. The function
473  * returns NULL if no segment with this name exists and otherwise a
474  * cc65_segmentinfo structure with one entry that contains the requested
475  * information.
476  */
477
478 void cc65_free_segmentinfo (cc65_dbginfo handle, const cc65_segmentinfo* info);
479 /* Free a segment info record */
480
481
482
483 /*****************************************************************************/
484 /*                                  Symbols                                  */
485 /*****************************************************************************/
486
487
488
489 /* Symbol information */
490 typedef enum {
491     CC65_SYM_EQUATE,
492     CC65_SYM_LABEL,                     /* Some sort of address */
493     CC65_SYM_IMPORT,                    /* An import */
494 } cc65_symbol_type;
495
496 /* Notes:
497  *  - If the symbol is segment relative, the segment id gives segment
498  *    information, otherwise it contains CC65_INV_ID.
499  *  - If the type is CC65_SYM_IMPORT, export_id may contain the id of the
500  *    export. This is not the case if the module contaiing the export doesn't
501  *    have debug information.
502  *  - For an import, the fields symbol_value and segment_id are taken from
503  *    the export, if it is available, since imports have no value or segments
504  *    by itself.
505  *  - For an import symbol_size doesn't have a meaning.
506  *  - For normal symbols (not cheap locals) parent_id contains CC65_INV_ID,
507  *    for cheap locals it contains the symbol id of the parent symbol.
508  */
509 typedef struct cc65_symboldata cc65_symboldata;
510 struct cc65_symboldata {
511     unsigned            symbol_id;      /* Id of symbol */
512     const char*         symbol_name;    /* Name of symbol */
513     cc65_symbol_type    symbol_type;    /* Type of symbol */
514     cc65_size           symbol_size;    /* Size of symbol, 0 if unknown */
515     long                symbol_value;   /* Value of symbol */
516     unsigned            export_id;      /* For imports: Matching export */
517     unsigned            segment_id;     /* Id of segment if any */
518     unsigned            scope_id;       /* The scope this symbol is in */
519     unsigned            parent_id;      /* Parent symbol for cheap locals */
520 };
521
522 typedef struct cc65_symbolinfo cc65_symbolinfo;
523 struct cc65_symbolinfo {
524     unsigned            count;          /* Number of data sets that follow */
525     cc65_symboldata     data[1];        /* Data sets, number is dynamic */
526 };
527
528
529
530 const cc65_symbolinfo* cc65_symbol_byid (cc65_dbginfo handle, unsigned id);
531 /* Return the symbol with a given id. The function returns NULL if no symbol
532  * with this id was found.
533  */
534
535 const cc65_symbolinfo* cc65_symbol_byname (cc65_dbginfo handle, const char* name);
536 /* Return a list of symbols with a given name. The function returns NULL if
537  * no symbol with this name was found.
538  */
539
540 const cc65_symbolinfo* cc65_symbol_byscope (cc65_dbginfo handle,
541                                             unsigned scope_id);
542 /* Return a list of symbols in the given scope. This includes cheap local
543  * symbols, but not symbols in subscopes. The function returns NULL if the
544  * scope id is invalid (no such scope) and otherwise a - possibly empty -
545  * symbol list.
546  */
547
548 const cc65_symbolinfo* cc65_symbol_inrange (cc65_dbginfo handle,
549                                             cc65_addr start, cc65_addr end);
550 /* Return a list of labels in the given range. end is inclusive. The function
551  * return NULL if no symbols within the given range are found. Non label
552  * symbols are ignored and not returned.
553  */
554
555 void cc65_free_symbolinfo (cc65_dbginfo handle, const cc65_symbolinfo* info);
556 /* Free a symbol info record */
557
558
559
560 /*****************************************************************************/
561 /*                                   Types                                   */
562 /*****************************************************************************/
563
564
565
566 /* Type information */
567 typedef enum {
568     CC65_TYPE_VOID,
569     CC65_TYPE_BYTE,
570     CC65_TYPE_WORD,
571     CC65_TYPE_DBYTE,
572     CC65_TYPE_DWORD,
573     CC65_TYPE_PTR,
574     CC65_TYPE_FARPTR,
575     CC65_TYPE_ARRAY,
576
577     /* The following ones are currently unavailable: */
578     CC65_TYPE_UNION,
579     CC65_TYPE_STRUCT,
580     CC65_TYPE_FUNC,
581 } cc65_typetoken;
582
583
584 /* A type is a linked list of typedata structures. In case of arrays, the
585  * structure will contain an element count and the element type. In case of
586  * pointers, the structure will contain the type of the data, the pointer
587  * points to (currently, there are only VOID pointers).
588  * The next pointer points to the next entry in the list. It is NULL if the
589  * end of the list is reached.
590  */
591 typedef struct cc65_typedata cc65_typedata;
592 struct cc65_typedata {
593     cc65_typedata*                next;         /* Pointer to next entry */
594     cc65_typetoken                what;         /* What kind of type is it? */
595     cc65_size                     size;         /* The size of the data */
596
597     /* Depending on "what", one of the members of this union follows */
598     union {
599
600         /* In case of CC65_TYPE_PTR or CC65_TYPE_FARPTR */
601         struct {
602             const cc65_typedata*  ind_type;     /* Type the pointer points to */
603         } ptr;
604
605         /* In case of CC65_TYPE_ARRAY */
606         struct {
607             cc65_size             ele_count;    /* Element count */
608             const cc65_typedata*  ele_type;     /* Element type */
609         } array;
610
611     } data;
612 };
613
614
615
616 const cc65_typedata* cc65_type_byid (cc65_dbginfo handle, unsigned id);
617 /* Return the data for the type with the given id. The function returns NULL
618  * if no type with this id was found.
619  */
620
621 void cc65_free_typedata (cc65_dbginfo Handle, const cc65_typedata* data);
622 /* Free a symbol info record */
623
624
625
626 /* Allow usage from C++ */
627 #ifdef __cplusplus     
628 }
629 #endif
630
631
632
633 /* End of dbginfo.h */
634 #endif
635
636
637