libyasm/symrec.h

   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