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