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 /* Pointer to an opaque data structure containing information from the debug
  62  * info file. Actually a handle to the data in the file.
  63  */
  64 typedef void* cc65_dbginfo;
  65
  66 /* Severity for cc65_parseerror */
  67 typedef enum {
  68     CC65_WARNING,
  69     CC65_ERROR,
  70 } cc65_error_severity;
  71
  72 /* Warnings/errors in cc65_read_dbginfo are passed via this struct */
  73 typedef struct cc65_parseerror cc65_parseerror;
  74 struct cc65_parseerror {
  75     cc65_error_severity type;           /* Type of error */
  76     const char*         name;           /* Name of input file */
  77     cc65_line           line;           /* Error line */
  78     unsigned            column;         /* Error column */
  79     char                errormsg[1];    /* Error message */
  80 };
  81
  82 /* Function that is called in case of parse errors */
  83 typedef void (*cc65_errorfunc) (const struct cc65_parseerror*);
  84
  85 /* Type of line */
  86 typedef enum {
  87     CC65_LINE_ASM,                      /* Assembler source */
  88     CC65_LINE_EXT,                      /* Externally supplied (= C) */
  89     CC65_LINE_MACRO,                    /* Macro expansion */
  90 } cc65_line_type;
  91
  92 /* Line information.
  93  * Notes:
  94  *   - line_end is inclusive
  95  *   - output_name may be NULL if the data wasn't written to the output file
  96  *     (example: bss segment)
  97  *   - output_offs is invalid if there is no output_name, and may not be of
  98  *     much use in case of a relocatable output file
  99  */
 100 typedef struct cc65_linedata cc65_linedata;
 101 struct cc65_linedata {
 102     const char*         source_name;    /* Name of the file */
 103     unsigned long       source_size;    /* Size of file */
 104     unsigned long       source_mtime;   /* Modification time */
 105     cc65_line           source_line;    /* Line number */
 106     cc65_addr           line_start;     /* Start address for this line */
 107     cc65_addr           line_end;       /* End address for this line */
 108     const char*         output_name;    /* Output file */
 109     unsigned long       output_offs;    /* Offset in output file */
 110     cc65_line_type      line_type;      /* Type of line */
 111     unsigned            count;          /* Nesting counter for macros */
 112 };
 113
 114 typedef struct cc65_lineinfo cc65_lineinfo;
 115 struct cc65_lineinfo {
 116     unsigned            count;          /* Number of data sets that follow */
 117     cc65_linedata       data[1];        /* Data sets, number is dynamic */
 118 };
 119
 120 /* Source file information */
 121 typedef struct cc65_sourcedata cc65_sourcedata;
 122 struct cc65_sourcedata {
 123     const char*         source_name;    /* Name of the file */
 124     unsigned long       source_size;    /* Size of file */
 125     unsigned long       source_mtime;   /* Modification time */
 126 };
 127
 128 typedef struct cc65_sourceinfo cc65_sourceinfo;
 129 struct cc65_sourceinfo {
 130     unsigned            count;          /* Number of data sets that follow */
 131     cc65_sourcedata     data[1];        /* Data sets, number is dynamic */
 132 };
 133
 134 /* Segment information.
 135  * Notes:
 136  *   - output_name may be NULL if the data wasn't written to the output file
 137  *     (example: bss segment)
 138  *   - output_offs is invalid if there is no output_name, and may not be of
 139  *     much use in case of a relocatable output file
 140  */
 141 typedef struct cc65_segmentdata cc65_segmentdata;
 142 struct cc65_segmentdata {
 143     const char*         segment_name;   /* Name of the segment */
 144     cc65_addr           segment_start;  /* Start address of segment */
 145     cc65_addr           segment_size;   /* Size of segment */
 146     const char*         output_name;    /* Output file this seg was written to */
 147     unsigned long       output_offs;    /* Offset of this seg in output file */
 148 };
 149
 150 typedef struct cc65_segmentinfo cc65_segmentinfo;
 151 struct cc65_segmentinfo {
 152     unsigned            count;          /* Number of data sets that follow */
 153     cc65_segmentdata    data[1];        /* Data sets, number is dynamic */
 154 };
 155
 156 /* Symbol information */
 157 typedef enum {
 158     CC65_SYM_EQUATE,
 159     CC65_SYM_LABEL                      /* Some sort of address */
 160 } cc65_symbol_type;
 161
 162 typedef struct cc65_symboldata cc65_symboldata;
 163 struct cc65_symboldata {
 164     const char*         symbol_name;    /* Name of symbol */
 165     cc65_symbol_type    symbol_type;    /* Type of symbol */
 166     cc65_size           symbol_size;    /* Size of symbol, 0 if unknown */
 167     long                symbol_value;   /* Value of symbol */
 168 };
 169
 170 typedef struct cc65_symbolinfo cc65_symbolinfo;
 171 struct cc65_symbolinfo {
 172     unsigned            count;          /* Number of data sets that follow */
 173     cc65_symboldata     data[1];        /* Data sets, number is dynamic */
 174 };
 175
 176
 177
 178 /*****************************************************************************/
 179 /*                                   Code                                    */
 180 /*****************************************************************************/
 181
 182
 183
 184 cc65_dbginfo cc65_read_dbginfo (const char* filename, cc65_errorfunc errorfunc);
 185 /* Parse the debug info file with the given name. On success, the function
 186  * will return a pointer to an opaque cc65_dbginfo structure, that must be
 187  * passed to the other functions in this module to retrieve information.
 188  * errorfunc is called in case of warnings and errors. If the file cannot be
 189  * read successfully, NULL is returned.
 190  */
 191
 192 void cc65_free_dbginfo (cc65_dbginfo Handle);
 193 /* Free debug information read from a file */
 194
 195 cc65_lineinfo* cc65_lineinfo_byaddr (cc65_dbginfo handle, unsigned long addr);
 196 /* Return line information for the given address. The function returns NULL
 197  * if no line information was found.
 198  */
 199
 200 cc65_lineinfo* cc65_lineinfo_byname (cc65_dbginfo handle, const char* filename,
 201                                      cc65_line line);
 202 /* Return line information for a file/line number combination. The function
 203  * returns NULL if no line information was found.
 204  */
 205
 206 void cc65_free_lineinfo (cc65_dbginfo handle, cc65_lineinfo* info);
 207 /* Free line info returned by one of the other functions */
 208
 209 cc65_sourceinfo* cc65_get_sourcelist (cc65_dbginfo handle);
 210 /* Return a list of all source files */
 211
 212 void cc65_free_sourceinfo (cc65_dbginfo handle, cc65_sourceinfo* info);
 213 /* Free a source info record */
 214
 215 cc65_segmentinfo* cc65_get_segmentlist (cc65_dbginfo handle);
 216 /* Return a list of all segments referenced in the debug information */
 217
 218 void cc65_free_segmentinfo (cc65_dbginfo handle, cc65_segmentinfo* info);
 219 /* Free a segment info record */
 220
 221 cc65_symbolinfo* cc65_symbol_byname (cc65_dbginfo handle, const char* name);
 222 /* Return a list of symbols with a given name. The function returns NULL if
 223  * no symbol with this name was found.
 224  */
 225
 226 cc65_symbolinfo* cc65_symbol_inrange (cc65_dbginfo handle,
 227                                       cc65_addr start, cc65_addr end);
 228 /* Return a list of labels in the given range. end is inclusive. The function
 229  * return NULL if no symbols within the given range are found. Non label
 230  * symbols are ignored and not returned.
 231  */
 232
 233 void cc65_free_symbolinfo (cc65_dbginfo Handle, cc65_symbolinfo* Info);
 234 /* Free a symbol info record */
 235
 236
 237
 238 /* Allow usage from C++ */
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243
 244
 245 /* End of dbginfo.h */
 246 #endif
 247
 248
 249