1 /** 2 * \file libyasm/symrec.h 3 * \brief YASM symbol table interface. 4 * 5 * \license 6 * Copyright (C) 2001-2007 Michael Urman, Peter Johnson 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * - Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * - Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND OTHER CONTRIBUTORS ``AS IS'' 18 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR OTHER CONTRIBUTORS BE 21 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27 * POSSIBILITY OF SUCH DAMAGE. 28 * \endlicense 29 */ 30 #ifndef YASM_SYMREC_H 31 #define YASM_SYMREC_H 32 33 #ifndef YASM_LIB_DECL 34 #define YASM_LIB_DECL 35 #endif 36 37 /** Symbol status. YASM_SYM_DEFINED is set by yasm_symtab_define_label(), 38 * yasm_symtab_define_equ(), or yasm_symtab_declare()/yasm_symrec_declare() 39 * with a visibility of #YASM_SYM_EXTERN or #YASM_SYM_COMMON. 40 */ 41 typedef enum yasm_sym_status { 42 YASM_SYM_NOSTATUS = 0, /**< no status */ 43 YASM_SYM_USED = 1 << 0, /**< for use before definition */ 44 YASM_SYM_DEFINED = 1 << 1, /**< once it's been defined in the file */ 45 YASM_SYM_VALUED = 1 << 2, /**< once its value has been determined */ 46 YASM_SYM_NOTINTABLE = 1 << 3 /**< if it's not in sym_table (ex. '$') */ 47 } yasm_sym_status; 48 49 /** Symbol record visibility. 50 * \note YASM_SYM_EXTERN and YASM_SYM_COMMON are mutually exclusive. 51 */ 52 typedef enum yasm_sym_vis { 53 YASM_SYM_LOCAL = 0, /**< Default, local only */ 54 YASM_SYM_GLOBAL = 1 << 0, /**< If symbol is declared GLOBAL */ 55 YASM_SYM_COMMON = 1 << 1, /**< If symbol is declared COMMON */ 56 YASM_SYM_EXTERN = 1 << 2, /**< If symbol is declared EXTERN */ 57 YASM_SYM_DLOCAL = 1 << 3 /**< If symbol is explicitly declared LOCAL */ 58 } yasm_sym_vis; 59 60 /** Create a new symbol table. */ 61 YASM_LIB_DECL 62 yasm_symtab *yasm_symtab_create(void); 63 64 /** Destroy a symbol table and all internal symbols. 65 * \param symtab symbol table 66 * \warning All yasm_symrec *'s into this symbol table become invalid after 67 * this is called! 68 */ 69 YASM_LIB_DECL 70 void yasm_symtab_destroy(/*@only@*/ yasm_symtab *symtab); 71 72 /** Set the symbol table to be case sensitive or not. 73 * Should be called before adding any symbol. 74 * \param symtab symbol table 75 * \param sensitive whether the symbol table should be case sensitive. 76 */ 77 YASM_LIB_DECL 78 void yasm_symtab_set_case_sensitive(yasm_symtab *symtab, int sensitive); 79 80 /** Get a reference to the symbol table's "absolute" symbol. This is 81 * essentially an EQU with no name and value 0, and is used for relocating 82 * absolute current-position-relative values. 83 * \see yasm_value_set_curpos_rel(). 84 * \param symtab symbol table 85 * \return Absolute symbol (dependent pointer, do not free). 86 */ 87 YASM_LIB_DECL 88 /*@dependent@*/ yasm_symrec *yasm_symtab_abs_sym(yasm_symtab *symtab); 89 90 /** Get a reference to (use) a symbol. The symbol does not necessarily need to 91 * be defined before it is used. 92 * \param symtab symbol table 93 * \param name symbol name 94 * \param line virtual line where referenced 95 * \return Symbol (dependent pointer, do not free). 96 */ 97 YASM_LIB_DECL 98 /*@dependent@*/ yasm_symrec *yasm_symtab_use 99 (yasm_symtab *symtab, const char *name, unsigned long line); 100 101 /** Get a reference to a symbol, without "using" it. Should be used for cases 102 * when an internal assembler usage of a symbol shouldn't be treated like a 103 * normal user symbol usage. 104 * \param symtab symbol table 105 * \param name symbol name 106 * \return Symbol (dependent pointer, do not free). May be NULL if symbol 107 * doesn't exist. 108 */ 109 YASM_LIB_DECL 110 /*@null@*/ /*@dependent@*/ yasm_symrec *yasm_symtab_get 111 (yasm_symtab *symtab, const char *name); 112 113 /** Define a symbol as an EQU value. 114 * \param symtab symbol table 115 * \param name symbol (EQU) name 116 * \param e EQU value (expression) 117 * \param line virtual line of EQU 118 * \return Symbol (dependent pointer, do not free). 119 */ 120 YASM_LIB_DECL 121 /*@dependent@*/ yasm_symrec *yasm_symtab_define_equ 122 (yasm_symtab *symtab, const char *name, /*@keep@*/ yasm_expr *e, 123 unsigned long line); 124 125 /** Define a symbol as a label. 126 * \param symtab symbol table 127 * \param name symbol (label) name 128 * \param precbc bytecode preceding label 129 * \param in_table nonzero if the label should be inserted into the symbol 130 * table (some specially-generated ones should not be) 131 * \param line virtual line of label 132 * \return Symbol (dependent pointer, do not free). 133 */ 134 YASM_LIB_DECL 135 /*@dependent@*/ yasm_symrec *yasm_symtab_define_label 136 (yasm_symtab *symtab, const char *name, 137 /*@dependent@*/ yasm_bytecode *precbc, int in_table, unsigned long line); 138 139 /** Define a symbol as a label representing the current assembly position. 140 * This should be used for this purpose instead of yasm_symtab_define_label() 141 * as value_finalize_scan() looks for usage of this symbol type for special 142 * handling. The symbol created is not inserted into the symbol table. 143 * \param symtab symbol table 144 * \param name symbol (label) name 145 * \param precbc bytecode preceding label 146 * \param line virtual line of label 147 * \return Symbol (dependent pointer, do not free). 148 */ 149 YASM_LIB_DECL 150 /*@dependent@*/ yasm_symrec *yasm_symtab_define_curpos 151 (yasm_symtab *symtab, const char *name, 152 /*@dependent@*/ yasm_bytecode *precbc, unsigned long line); 153 154 /** Define a special symbol that will appear in the symbol table and have a 155 * defined name, but have no other data associated with it within the 156 * standard symrec. 157 * \param symtab symbol table 158 * \param name symbol name 159 * \param vis symbol visibility 160 * \return Symbol (dependent pointer, do not free). 161 */ 162 YASM_LIB_DECL 163 /*@dependent@*/ yasm_symrec *yasm_symtab_define_special 164 (yasm_symtab *symtab, const char *name, yasm_sym_vis vis); 165 166 /** Declare external visibility of a symbol. 167 * \note Not all visibility combinations are allowed. 168 * \param symtab symbol table 169 * \param name symbol name 170 * \param vis visibility 171 * \param line virtual line of visibility-setting 172 * \return Symbol (dependent pointer, do not free). 173 */ 174 YASM_LIB_DECL 175 /*@dependent@*/ yasm_symrec *yasm_symtab_declare 176 (yasm_symtab *symtab, const char *name, yasm_sym_vis vis, 177 unsigned long line); 178 179 /** Declare external visibility of a symbol. 180 * \note Not all visibility combinations are allowed. 181 * \param symrec symbol 182 * \param vis visibility 183 * \param line virtual line of visibility-setting 184 */ 185 YASM_LIB_DECL 186 void yasm_symrec_declare(yasm_symrec *symrec, yasm_sym_vis vis, 187 unsigned long line); 188 189 /** Callback function for yasm_symrec_traverse(). 190 * \param sym symbol 191 * \param d data passed into yasm_symrec_traverse() 192 * \return Nonzero to stop symbol traversal. 193 */ 194 typedef int (*yasm_symtab_traverse_callback) 195 (yasm_symrec *sym, /*@null@*/ void *d); 196 197 /** Traverse all symbols in the symbol table. 198 * \param symtab symbol table 199 * \param d data to pass to each call of callback function 200 * \param func callback function called on each symbol 201 * \return Nonzero value returned by callback function if it ever returned 202 * nonzero. 203 */ 204 YASM_LIB_DECL 205 int /*@alt void@*/ yasm_symtab_traverse 206 (yasm_symtab *symtab, /*@null@*/ void *d, 207 yasm_symtab_traverse_callback func); 208 209 /** Symbol table iterator (opaque type). */ 210 typedef struct yasm_symtab_iter yasm_symtab_iter; 211 212 /** Get an iterator pointing to the first symbol in the symbol table. 213 * \param symtab symbol table 214 * \return Iterator for the symbol table. 215 */ 216 YASM_LIB_DECL 217 const yasm_symtab_iter *yasm_symtab_first(const yasm_symtab *symtab); 218 219 /** Move a symbol table iterator to the next symbol in the symbol table. 220 * \param prev Previous iterator value 221 * \return Next iterator value, or NULL if no more symbols in the table. 222 */ 223 YASM_LIB_DECL 224 /*@null@*/ const yasm_symtab_iter *yasm_symtab_next 225 (const yasm_symtab_iter *prev); 226 227 /** Get the symbol corresponding to the current symbol table iterator value. 228 * \param cur iterator value 229 * \return Corresponding symbol. 230 */ 231 YASM_LIB_DECL 232 yasm_symrec *yasm_symtab_iter_value(const yasm_symtab_iter *cur); 233 234 /** Finalize symbol table after parsing stage. Checks for symbols that are 235 * used but never defined or declared #YASM_SYM_EXTERN or #YASM_SYM_COMMON. 236 * \param symtab symbol table 237 * \param undef_extern if nonzero, all undef syms should be declared extern 238 * \param errwarns error/warning set 239 * \note Errors/warnings are stored into errwarns. 240 */ 241 YASM_LIB_DECL 242 void yasm_symtab_parser_finalize(yasm_symtab *symtab, int undef_extern, 243 yasm_errwarns *errwarns); 244 245 /** Print the symbol table. For debugging purposes. 246 * \param symtab symbol table 247 * \param f file 248 * \param indent_level indentation level 249 */ 250 YASM_LIB_DECL 251 void yasm_symtab_print(yasm_symtab *symtab, FILE *f, int indent_level); 252 253 /** Get the name of a symbol. 254 * \param sym symbol 255 * \return Symbol name. 256 */ 257 YASM_LIB_DECL 258 /*@observer@*/ const char *yasm_symrec_get_name(const yasm_symrec *sym); 259 260 /** Get the externally-visible (global) name of a symbol. 261 * \param sym symbol 262 * \param object object 263 * \return Externally-visible symbol name (allocated, caller must free). 264 */ 265 YASM_LIB_DECL 266 /*@only@*/ char *yasm_symrec_get_global_name(const yasm_symrec *sym, 267 const yasm_object *object); 268 269 /** Get the visibility of a symbol. 270 * \param sym symbol 271 * \return Symbol visibility. 272 */ 273 YASM_LIB_DECL 274 yasm_sym_vis yasm_symrec_get_visibility(const yasm_symrec *sym); 275 276 /** Get the status of a symbol. 277 * \param sym symbol 278 * \return Symbol status. 279 */ 280 YASM_LIB_DECL 281 yasm_sym_status yasm_symrec_get_status(const yasm_symrec *sym); 282 283 /** Get the virtual line of where a symbol was first defined. 284 * \param sym symbol 285 * \return line virtual line 286 */ 287 YASM_LIB_DECL 288 unsigned long yasm_symrec_get_def_line(const yasm_symrec *sym); 289 290 /** Get the virtual line of where a symbol was first declared. 291 * \param sym symbol 292 * \return line virtual line 293 */ 294 YASM_LIB_DECL 295 unsigned long yasm_symrec_get_decl_line(const yasm_symrec *sym); 296 297 /** Get the virtual line of where a symbol was first used. 298 * \param sym symbol 299 * \return line virtual line 300 */ 301 YASM_LIB_DECL 302 unsigned long yasm_symrec_get_use_line(const yasm_symrec *sym); 303 304 /** Get EQU value of a symbol. 305 * \param sym symbol 306 * \return EQU value, or NULL if symbol is not an EQU or is not defined. 307 */ 308 YASM_LIB_DECL 309 /*@observer@*/ /*@null@*/ const yasm_expr *yasm_symrec_get_equ 310 (const yasm_symrec *sym); 311 312 /** Dependent pointer to a bytecode. */ 313 typedef /*@dependent@*/ yasm_bytecode *yasm_symrec_get_label_bytecodep; 314 315 /** Get the label location of a symbol. 316 * \param sym symbol 317 * \param precbc bytecode preceding label (output) 318 * \return 0 if not symbol is not a label or if the symbol's visibility is 319 * #YASM_SYM_EXTERN or #YASM_SYM_COMMON (not defined in the file). 320 */ 321 YASM_LIB_DECL 322 int yasm_symrec_get_label(const yasm_symrec *sym, 323 /*@out@*/ yasm_symrec_get_label_bytecodep *precbc); 324 325 /** Set the size of a symbol. 326 * \param sym symbol 327 * \param size size to be set 328 */ 329 void yasm_symrec_set_size(yasm_symrec *sym, int size); 330 331 /** Get the size of a symbol. 332 * \param sym symbol 333 * \return size of the symbol, 0 if none specified by the user. 334 */ 335 int yasm_symrec_get_size(const yasm_symrec *sym); 336 337 /** Set the segment of a symbol. 338 * \param sym symbol 339 * \param segment segment to be set 340 */ 341 void yasm_symrec_set_segment(yasm_symrec *sym, const char *segment); 342 343 /** Get the segment of a symbol. 344 * \param sym symbol 345 * \return segment of the symbol, NULL if none specified by the user. 346 */ 347 const char *yasm_symrec_get_segment(const yasm_symrec *sym); 348 349 /** Determine if symbol is the "absolute" symbol created by 350 * yasm_symtab_abs_sym(). 351 * \param sym symbol 352 * \return 0 if symbol is not the "absolute" symbol, nonzero otherwise. 353 */ 354 YASM_LIB_DECL 355 int yasm_symrec_is_abs(const yasm_symrec *sym); 356 357 /** Determine if symbol is a special symbol. 358 * \param sym symbol 359 * \return 0 if symbol is not a special symbol, nonzero otherwise. 360 */ 361 YASM_LIB_DECL 362 int yasm_symrec_is_special(const yasm_symrec *sym); 363 364 /** Determine if symbol is a label representing the current assembly position. 365 * \param sym symbol 366 * \return 0 if symbol is not a current position label, nonzero otherwise. 367 */ 368 YASM_LIB_DECL 369 int yasm_symrec_is_curpos(const yasm_symrec *sym); 370 371 /** Set object-extended valparams. 372 * \param sym symbol 373 * \param objext_valparams object-extended valparams 374 */ 375 YASM_LIB_DECL 376 void yasm_symrec_set_objext_valparams 377 (yasm_symrec *sym, /*@only@*/ yasm_valparamhead *objext_valparams); 378 379 /** Get object-extended valparams, if any, associated with symbol's 380 * declaration. 381 * \param sym symbol 382 * \return Object-extended valparams (NULL if none). 383 */ 384 YASM_LIB_DECL 385 /*@null@*/ /*@dependent@*/ yasm_valparamhead *yasm_symrec_get_objext_valparams 386 (yasm_symrec *sym); 387 388 /** Set common size of symbol. 389 * \param sym symbol 390 * \param common_size common size expression 391 */ 392 YASM_LIB_DECL 393 void yasm_symrec_set_common_size 394 (yasm_symrec *sym, /*@only@*/ yasm_expr *common_size); 395 396 /** Get common size of symbol, if symbol is declared COMMON and a size was set 397 * for it. 398 * \param sym symbol 399 * \return Common size (NULL if none). 400 */ 401 YASM_LIB_DECL 402 /*@dependent@*/ /*@null@*/ yasm_expr **yasm_symrec_get_common_size 403 (yasm_symrec *sym); 404 405 /** Get associated data for a symbol and data callback. 406 * \param sym symbol 407 * \param callback callback used when adding data 408 * \return Associated data (NULL if none). 409 */ 410 YASM_LIB_DECL 411 /*@dependent@*/ /*@null@*/ void *yasm_symrec_get_data 412 (yasm_symrec *sym, const yasm_assoc_data_callback *callback); 413 414 /** Add associated data to a symbol. 415 * \attention Deletes any existing associated data for that data callback. 416 * \param sym symbol 417 * \param callback callback 418 * \param data data to associate 419 */ 420 YASM_LIB_DECL 421 void yasm_symrec_add_data(yasm_symrec *sym, 422 const yasm_assoc_data_callback *callback, 423 /*@only@*/ /*@null@*/ void *data); 424 425 /** Print a symbol. For debugging purposes. 426 * \param f file 427 * \param indent_level indentation level 428 * \param sym symbol 429 */ 430 YASM_LIB_DECL 431 void yasm_symrec_print(const yasm_symrec *sym, FILE *f, int indent_level); 432 433 #endif 434