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 */ 41typedef 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 */ 52typedef 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. */ 61YASM_LIB_DECL 62yasm_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 */ 69YASM_LIB_DECL 70void 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 */ 77YASM_LIB_DECL 78void 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 */ 87YASM_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 */ 97YASM_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 */ 109YASM_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 */ 120YASM_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 */ 134YASM_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 */ 149YASM_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 */ 162YASM_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 */ 174YASM_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 */ 185YASM_LIB_DECL 186void 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 */ 194typedef 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 */ 204YASM_LIB_DECL 205int /*@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). */ 210typedef 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 */ 216YASM_LIB_DECL 217const 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 */ 223YASM_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 */ 231YASM_LIB_DECL 232yasm_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 */ 241YASM_LIB_DECL 242void 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 */ 250YASM_LIB_DECL 251void 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 */ 257YASM_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 */ 265YASM_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 */ 273YASM_LIB_DECL 274yasm_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 */ 280YASM_LIB_DECL 281yasm_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 */ 287YASM_LIB_DECL 288unsigned 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 */ 294YASM_LIB_DECL 295unsigned 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 */ 301YASM_LIB_DECL 302unsigned 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 */ 308YASM_LIB_DECL 309/*@observer@*/ /*@null@*/ const yasm_expr *yasm_symrec_get_equ 310 (const yasm_symrec *sym); 311 312/** Dependent pointer to a bytecode. */ 313typedef /*@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 */ 321YASM_LIB_DECL 322int 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 */ 329void 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 */ 335int 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 */ 341void 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 */ 347const 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 */ 354YASM_LIB_DECL 355int 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 */ 361YASM_LIB_DECL 362int 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 */ 368YASM_LIB_DECL 369int 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 */ 375YASM_LIB_DECL 376void 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 */ 384YASM_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 */ 392YASM_LIB_DECL 393void 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 */ 401YASM_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 */ 410YASM_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 */ 420YASM_LIB_DECL 421void 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 */ 430YASM_LIB_DECL 431void yasm_symrec_print(const yasm_symrec *sym, FILE *f, int indent_level); 432 433#endif 434