1130803Smarcel/* Interface to C preprocessor macro tables for GDB. 2130803Smarcel Copyright 2002 Free Software Foundation, Inc. 3130803Smarcel Contributed by Red Hat, Inc. 4130803Smarcel 5130803Smarcel This file is part of GDB. 6130803Smarcel 7130803Smarcel This program is free software; you can redistribute it and/or modify 8130803Smarcel it under the terms of the GNU General Public License as published by 9130803Smarcel the Free Software Foundation; either version 2 of the License, or 10130803Smarcel (at your option) any later version. 11130803Smarcel 12130803Smarcel This program is distributed in the hope that it will be useful, 13130803Smarcel but WITHOUT ANY WARRANTY; without even the implied warranty of 14130803Smarcel MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15130803Smarcel GNU General Public License for more details. 16130803Smarcel 17130803Smarcel You should have received a copy of the GNU General Public License 18130803Smarcel along with this program; if not, write to the Free Software 19130803Smarcel Foundation, Inc., 59 Temple Place - Suite 330, 20130803Smarcel Boston, MA 02111-1307, USA. */ 21130803Smarcel 22130803Smarcel#ifndef MACROTAB_H 23130803Smarcel#define MACROTAB_H 24130803Smarcel 25130803Smarcelstruct obstack; 26130803Smarcelstruct bcache; 27130803Smarcel 28130803Smarcel/* How do we represent a source location? I mean, how should we 29130803Smarcel represent them within GDB; the user wants to use all sorts of 30130803Smarcel ambiguous abbreviations, like "break 32" and "break foo.c:32" 31130803Smarcel ("foo.c" may have been #included into several compilation units), 32130803Smarcel but what do we disambiguate those things to? 33130803Smarcel 34130803Smarcel - Answer 1: "Filename and line number." (Or column number, if 35130803Smarcel you're picky.) That's not quite good enough. For example, the 36130803Smarcel same source file can be #included into several different 37130803Smarcel compilation units --- which #inclusion do you mean? 38130803Smarcel 39130803Smarcel - Answer 2: "Compilation unit, filename, and line number." This is 40130803Smarcel a pretty good answer; GDB's `struct symtab_and_line' basically 41130803Smarcel embodies this representation. But it's still ambiguous; what if a 42130803Smarcel given compilation unit #includes the same file twice --- how can I 43130803Smarcel set a breakpoint on line 12 of the fifth #inclusion of "foo.c"? 44130803Smarcel 45130803Smarcel - Answer 3: "Compilation unit, chain of #inclusions, and line 46130803Smarcel number." This is analogous to the way GCC reports errors in 47130803Smarcel #include files: 48130803Smarcel 49130803Smarcel $ gcc -c base.c 50130803Smarcel In file included from header2.h:8, 51130803Smarcel from header1.h:3, 52130803Smarcel from base.c:5: 53130803Smarcel header3.h:1: parse error before ')' token 54130803Smarcel $ 55130803Smarcel 56130803Smarcel GCC tells you exactly what path of #inclusions led you to the 57130803Smarcel problem. It gives you complete information, in a way that the 58130803Smarcel following would not: 59130803Smarcel 60130803Smarcel $ gcc -c base.c 61130803Smarcel header3.h:1: parse error before ')' token 62130803Smarcel $ 63130803Smarcel 64130803Smarcel Converting all of GDB to use this is a big task, and I'm not really 65130803Smarcel suggesting it should be a priority. But this module's whole 66130803Smarcel purpose is to maintain structures describing the macro expansion 67130803Smarcel process, so I think it's appropriate for us to take a little care 68130803Smarcel to do that in a complete fashion. 69130803Smarcel 70130803Smarcel In this interface, the first line of a file is numbered 1, not 0. 71130803Smarcel This is the same convention the rest of GDB uses. */ 72130803Smarcel 73130803Smarcel 74130803Smarcel/* A table of all the macro definitions for a given compilation unit. */ 75130803Smarcelstruct macro_table; 76130803Smarcel 77130803Smarcel 78130803Smarcel/* A source file that participated in a compilation unit --- either a 79130803Smarcel main file, or an #included file. If a file is #included more than 80130803Smarcel once, the presence of the `included_from' and `included_at_line' 81130803Smarcel members means that we need to make one instance of this structure 82130803Smarcel for each #inclusion. Taken as a group, these structures form a 83130803Smarcel tree mapping the #inclusions that contributed to the compilation 84130803Smarcel unit, with the main source file as its root. 85130803Smarcel 86130803Smarcel Beware --- not every source file mentioned in a compilation unit's 87130803Smarcel symtab structures will appear in the #inclusion tree! As of Oct 88130803Smarcel 2002, GCC does record the effect of #line directives in the source 89130803Smarcel line info, but not in macro info. This means that GDB's symtabs 90130803Smarcel (built from the former, among other things) may mention filenames 91130803Smarcel that the #inclusion tree (built from the latter) doesn't have any 92130803Smarcel record of. See macroscope.c:sal_macro_scope for how to accomodate 93130803Smarcel this. 94130803Smarcel 95130803Smarcel It's worth noting that libcpp has a simpler way of representing all 96130803Smarcel this, which we should consider switching to. It might even be 97130803Smarcel suitable for ordinary non-macro line number info. 98130803Smarcel 99130803Smarcel Suppose you take your main source file, and after each line 100130803Smarcel containing an #include directive you insert the text of the 101130803Smarcel #included file. The result is a big file that pretty much 102130803Smarcel corresponds to the full text the compiler's going to see. There's 103130803Smarcel a one-to-one correspondence between lines in the big file and 104130803Smarcel per-inclusion lines in the source files. (Obviously, #include 105130803Smarcel directives that are #if'd out don't count. And you'll need to 106130803Smarcel append a newline to any file that doesn't end in one, to avoid 107130803Smarcel splicing the last #included line with the next line of the 108130803Smarcel #including file.) 109130803Smarcel 110130803Smarcel Libcpp calls line numbers in this big imaginary file "logical line 111130803Smarcel numbers", and has a data structure called a "line map" that can map 112130803Smarcel logical line numbers onto actual source filenames and line numbers, 113130803Smarcel and also tell you the chain of #inclusions responsible for any 114130803Smarcel particular logical line number. Basically, this means you can pass 115130803Smarcel around a single line number and some kind of "compilation unit" 116130803Smarcel object and you get nice, unambiguous source code locations that 117130803Smarcel distinguish between multiple #inclusions of the same file, etc. 118130803Smarcel 119130803Smarcel Pretty neat, huh? */ 120130803Smarcel 121130803Smarcelstruct macro_source_file 122130803Smarcel{ 123130803Smarcel 124130803Smarcel /* The macro table for the compilation unit this source location is 125130803Smarcel a part of. */ 126130803Smarcel struct macro_table *table; 127130803Smarcel 128130803Smarcel /* A source file --- possibly a header file. */ 129130803Smarcel const char *filename; 130130803Smarcel 131130803Smarcel /* The location we were #included from, or zero if we are the 132130803Smarcel compilation unit's main source file. */ 133130803Smarcel struct macro_source_file *included_by; 134130803Smarcel 135130803Smarcel /* If `included_from' is non-zero, the line number in that source 136130803Smarcel file at which we were included. */ 137130803Smarcel int included_at_line; 138130803Smarcel 139130803Smarcel /* Head of a linked list of the source files #included by this file; 140130803Smarcel our children in the #inclusion tree. This list is sorted by its 141130803Smarcel elements' `included_at_line' values, which are unique. (The 142130803Smarcel macro splay tree's ordering function needs this property.) */ 143130803Smarcel struct macro_source_file *includes; 144130803Smarcel 145130803Smarcel /* The next file #included by our `included_from' file; our sibling 146130803Smarcel in the #inclusion tree. */ 147130803Smarcel struct macro_source_file *next_included; 148130803Smarcel}; 149130803Smarcel 150130803Smarcel 151130803Smarcel/* Create a new, empty macro table. Allocate it in OBSTACK, or use 152130803Smarcel xmalloc if OBSTACK is zero. Use BCACHE to store all macro names, 153130803Smarcel arguments, definitions, and anything else that might be the same 154130803Smarcel amongst compilation units in an executable file; if BCACHE is zero, 155130803Smarcel don't cache these things. 156130803Smarcel 157130803Smarcel Note that, if either OBSTACK or BCACHE are non-zero, then you 158130803Smarcel should only ever add information the macro table --- you should 159130803Smarcel never remove things from it. You'll get an error if you try. At 160130803Smarcel the moment, since we only provide obstacks and bcaches for macro 161130803Smarcel tables for symtabs, this restriction makes a nice sanity check. 162130803Smarcel Obstacks and bcaches are pretty much grow-only structures anyway. 163130803Smarcel However, if we find that it's occasionally useful to delete things 164130803Smarcel even from the symtab's tables, and the storage leak isn't a 165130803Smarcel problem, this restriction could be lifted. */ 166130803Smarcelstruct macro_table *new_macro_table (struct obstack *obstack, 167130803Smarcel struct bcache *bcache); 168130803Smarcel 169130803Smarcel 170130803Smarcel/* Free TABLE, and any macro definitions, source file structures, 171130803Smarcel etc. it owns. This will raise an internal error if TABLE was 172130803Smarcel allocated on an obstack, or if it uses a bcache. */ 173130803Smarcelvoid free_macro_table (struct macro_table *table); 174130803Smarcel 175130803Smarcel 176130803Smarcel/* Set FILENAME as the main source file of TABLE. Return a source 177130803Smarcel file structure describing that file; if we record the #definition 178130803Smarcel of macros, or the #inclusion of other files into FILENAME, we'll 179130803Smarcel use that source file structure to indicate the context. 180130803Smarcel 181130803Smarcel The "main source file" is the one that was given to the compiler; 182130803Smarcel all other source files that contributed to the compilation unit are 183130803Smarcel #included, directly or indirectly, from this one. 184130803Smarcel 185130803Smarcel The macro table makes its own copy of FILENAME; the caller is 186130803Smarcel responsible for freeing FILENAME when it is no longer needed. */ 187130803Smarcelstruct macro_source_file *macro_set_main (struct macro_table *table, 188130803Smarcel const char *filename); 189130803Smarcel 190130803Smarcel 191130803Smarcel/* Return the main source file of the macro table TABLE. */ 192130803Smarcelstruct macro_source_file *macro_main (struct macro_table *table); 193130803Smarcel 194130803Smarcel 195130803Smarcel/* Record a #inclusion. 196130803Smarcel Record in SOURCE's macro table that, at line number LINE in SOURCE, 197130803Smarcel we #included the file INCLUDED. Return a source file structure we 198130803Smarcel can use for symbols #defined or files #included into that. If we've 199130803Smarcel already created a source file structure for this #inclusion, return 200130803Smarcel the same structure we created last time. 201130803Smarcel 202130803Smarcel The first line of the source file has a line number of 1, not 0. 203130803Smarcel 204130803Smarcel The macro table makes its own copy of INCLUDED; the caller is 205130803Smarcel responsible for freeing INCLUDED when it is no longer needed. */ 206130803Smarcelstruct macro_source_file *macro_include (struct macro_source_file *source, 207130803Smarcel int line, 208130803Smarcel const char *included); 209130803Smarcel 210130803Smarcel 211130803Smarcel/* Find any source file structure for a file named NAME, either 212130803Smarcel included into SOURCE, or SOURCE itself. Return zero if we have 213130803Smarcel none. NAME is only the final portion of the filename, not the full 214130803Smarcel path. e.g., `stdio.h', not `/usr/include/stdio.h'. If NAME 215130803Smarcel appears more than once in the inclusion tree, return the 216130803Smarcel least-nested inclusion --- the one closest to the main source file. */ 217130803Smarcelstruct macro_source_file *(macro_lookup_inclusion 218130803Smarcel (struct macro_source_file *source, 219130803Smarcel const char *name)); 220130803Smarcel 221130803Smarcel 222130803Smarcel/* Record an object-like #definition (i.e., one with no parameter list). 223130803Smarcel Record in SOURCE's macro table that, at line number LINE in SOURCE, 224130803Smarcel we #defined a preprocessor symbol named NAME, whose replacement 225130803Smarcel string is REPLACEMENT. This function makes copies of NAME and 226130803Smarcel REPLACEMENT; the caller is responsible for freeing them. */ 227130803Smarcelvoid macro_define_object (struct macro_source_file *source, int line, 228130803Smarcel const char *name, const char *replacement); 229130803Smarcel 230130803Smarcel 231130803Smarcel/* Record an function-like #definition (i.e., one with a parameter list). 232130803Smarcel 233130803Smarcel Record in SOURCE's macro table that, at line number LINE in SOURCE, 234130803Smarcel we #defined a preprocessor symbol named NAME, with ARGC arguments 235130803Smarcel whose names are given in ARGV, whose replacement string is REPLACEMENT. If 236130803Smarcel the macro takes a variable number of arguments, then ARGC should be 237130803Smarcel one greater than the number of named arguments, and ARGV[ARGC-1] 238130803Smarcel should be the string "...". This function makes its own copies of 239130803Smarcel NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing 240130803Smarcel them. */ 241130803Smarcelvoid macro_define_function (struct macro_source_file *source, int line, 242130803Smarcel const char *name, int argc, const char **argv, 243130803Smarcel const char *replacement); 244130803Smarcel 245130803Smarcel 246130803Smarcel/* Record an #undefinition. 247130803Smarcel Record in SOURCE's macro table that, at line number LINE in SOURCE, 248130803Smarcel we removed the definition for the preprocessor symbol named NAME. */ 249130803Smarcelvoid macro_undef (struct macro_source_file *source, int line, 250130803Smarcel const char *name); 251130803Smarcel 252130803Smarcel 253130803Smarcel/* Different kinds of macro definitions. */ 254130803Smarcelenum macro_kind 255130803Smarcel{ 256130803Smarcel macro_object_like, 257130803Smarcel macro_function_like 258130803Smarcel}; 259130803Smarcel 260130803Smarcel 261130803Smarcel/* A preprocessor symbol definition. */ 262130803Smarcelstruct macro_definition 263130803Smarcel{ 264130803Smarcel /* The table this definition lives in. */ 265130803Smarcel struct macro_table *table; 266130803Smarcel 267130803Smarcel /* What kind of macro it is. */ 268130803Smarcel enum macro_kind kind; 269130803Smarcel 270130803Smarcel /* If `kind' is `macro_function_like', the number of arguments it 271130803Smarcel takes, and their names. The names, and the array of pointers to 272130803Smarcel them, are in the table's bcache, if it has one. */ 273130803Smarcel int argc; 274130803Smarcel const char * const *argv; 275130803Smarcel 276130803Smarcel /* The replacement string (body) of the macro. This is in the 277130803Smarcel table's bcache, if it has one. */ 278130803Smarcel const char *replacement; 279130803Smarcel}; 280130803Smarcel 281130803Smarcel 282130803Smarcel/* Return a pointer to the macro definition for NAME in scope at line 283130803Smarcel number LINE of SOURCE. If LINE is -1, return the definition in 284130803Smarcel effect at the end of the file. The macro table owns the structure; 285130803Smarcel the caller need not free it. Return zero if NAME is not #defined 286130803Smarcel at that point. */ 287130803Smarcelstruct macro_definition *(macro_lookup_definition 288130803Smarcel (struct macro_source_file *source, 289130803Smarcel int line, const char *name)); 290130803Smarcel 291130803Smarcel 292130803Smarcel/* Return the source location of the definition for NAME in scope at 293130803Smarcel line number LINE of SOURCE. Set *DEFINITION_LINE to the line 294130803Smarcel number of the definition, and return a source file structure for 295130803Smarcel the file. Return zero if NAME has no definition in scope at that 296130803Smarcel point, and leave *DEFINITION_LINE unchanged. */ 297130803Smarcelstruct macro_source_file *(macro_definition_location 298130803Smarcel (struct macro_source_file *source, 299130803Smarcel int line, 300130803Smarcel const char *name, 301130803Smarcel int *definition_line)); 302130803Smarcel 303130803Smarcel 304130803Smarcel#endif /* MACROTAB_H */ 305