-/* $IdPath$
- * Expression handling header file
+/**
+ * \file expr.h
+ * \brief YASM expression interface
+ *
+ * $IdPath: yasm/libyasm/expr.h,v 1.39 2003/03/15 05:07:48 peter Exp $
*
* Copyright (C) 2001 Michael Urman, Peter Johnson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- * 1. Redistributions of source code must retain the above copyright
+ * - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
+ * - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
#ifndef YASM_EXPR_H
#define YASM_EXPR_H
+/** Expression item (opaque type). \internal */
typedef struct yasm_expr__item yasm_expr__item;
+/** Initialize expression internal data structures.
+ * \param a architecture in use
+ */
void yasm_expr_initialize(yasm_arch *a);
-/*@only@*/ yasm_expr *yasm_expr_new(yasm_expr_op, /*@only@*/ yasm_expr__item *,
- /*@only@*/ /*@null@*/ yasm_expr__item *,
- unsigned long lindex);
+/** Create a new expression e=a op b.
+ * \param op operation
+ * \param a expression item a
+ * \param b expression item b (optional depending on op)
+ * \param lindex line index (where expression defined)
+ * \return Newly allocated expression.
+ */
+/*@only@*/ yasm_expr *yasm_expr_new
+ (yasm_expr_op op, /*@only@*/ yasm_expr__item *a,
+ /*@only@*/ /*@null@*/ yasm_expr__item *b, unsigned long lindex);
+
+/** Create a new symbol expression item.
+ * \param sym symbol
+ * \return Newly allocated expression item.
+ */
+/*@only@*/ yasm_expr__item *yasm_expr_sym(/*@keep@*/ yasm_symrec *sym);
+
+/** Create a new expression expression item.
+ * \param e expression
+ * \return Newly allocated expression item.
+ */
+/*@only@*/ yasm_expr__item *yasm_expr_expr(/*@keep@*/ yasm_expr *e);
+
+/** Create a new intnum expression item.
+ * \param intn intnum
+ * \return Newly allocated expression item.
+ */
+/*@only@*/ yasm_expr__item *yasm_expr_int(/*@keep@*/ yasm_intnum *intn);
+
+/** Create a new floatnum expression item.
+ * \param flt floatnum
+ * \return Newly allocated expression item.
+ */
+/*@only@*/ yasm_expr__item *yasm_expr_float(/*@keep@*/ yasm_floatnum *flt);
-/*@only@*/ yasm_expr__item *yasm_expr_sym(/*@keep@*/ yasm_symrec *);
-/*@only@*/ yasm_expr__item *yasm_expr_expr(/*@keep@*/ yasm_expr *);
-/*@only@*/ yasm_expr__item *yasm_expr_int(/*@keep@*/ yasm_intnum *);
-/*@only@*/ yasm_expr__item *yasm_expr_float(/*@keep@*/ yasm_floatnum *);
+/** Create a new register expression item.
+ * \param reg register
+ * \return Newly allocated expression item.
+ */
/*@only@*/ yasm_expr__item *yasm_expr_reg(unsigned long reg);
+/** Create a new expression tree e=l op r.
+ * \param l expression for left side of new expression
+ * \param o operation
+ * \param r expression for right side of new expression
+ * \param i line index
+ * \return Newly allocated expression.
+ */
#define yasm_expr_new_tree(l,o,r,i) \
yasm_expr_new ((o), yasm_expr_expr(l), yasm_expr_expr(r), i)
+
+/** Create a new expression branch e=op r.
+ * \param o operation
+ * \param r expression for right side of new expression
+ * \param i line index
+ * \return Newly allocated expression.
+ */
#define yasm_expr_new_branch(o,r,i) \
yasm_expr_new ((o), yasm_expr_expr(r), (yasm_expr__item *)NULL, i)
+
+/** Create a new expression identity e=r.
+ * \param r expression for identity within new expression
+ * \param i line index
+ * \return Newly allocated expression.
+ */
#define yasm_expr_new_ident(r,i) \
yasm_expr_new (YASM_EXPR_IDENT, (r), (yasm_expr__item *)NULL, i)
-/* allocates and makes an exact duplicate of e */
+/** Duplicate an expression.
+ * \param e expression
+ * \return Newly allocated expression identical to e.
+ */
yasm_expr *yasm_expr_copy(const yasm_expr *e);
+/** Destroy (free allocated memory for) an expression.
+ * \param e expression
+ */
void yasm_expr_delete(/*@only@*/ /*@null@*/ yasm_expr *e);
-/* "Extra" transformation function that may be inserted into an
- * expr_level_tree() invocation.
- * Inputs: e, the expression being simplified
- * d, data provided as expr_xform_extra_data to expr_level_tree()
- * Returns updated e.
+/** Extra transformation function for yasm_expr__level_tree().
+ * \param e expression being simplified
+ * \param d data provided as expr_xform_extra_data to
+ * yasm_expr__level_tree()
+ * \return Transformed e.
*/
typedef /*@only@*/ yasm_expr * (*yasm_expr_xform_func)
(/*@returned@*/ /*@only@*/ yasm_expr *e, /*@null@*/ void *d);
+/** Linked list of expression entries.
+ * \internal
+ * Used internally by yasm_expr__level_tree().
+ */
typedef struct yasm__exprhead yasm__exprhead;
#ifdef YASM_INTERNAL
SLIST_HEAD(yasm__exprhead, yasm__exprentry);
#endif
-/* Level an entire expn tree. Call with eh = NULL */
+/** Level an entire expression tree.
+ * \internal
+ * \param e expression
+ * \param fold_const enable constant folding if nonzero
+ * \param simplify_ident simplify identities
+ * \param calc_bc_dist bytecode distance-calculation function
+ * \param expr_xform_extra extra transformation function
+ * \param expr_xform_extra_data data to pass to expr_xform_extra
+ * \param eh call with NULL (for internal use in recursion)
+ * \return Leveled expression.
+ */
/*@only@*/ /*@null@*/ yasm_expr *yasm_expr__level_tree
(/*@returned@*/ /*@only@*/ /*@null@*/ yasm_expr *e, int fold_const,
int simplify_ident, /*@null@*/ yasm_calc_bc_dist_func calc_bc_dist,
/*@null@*/ yasm_expr_xform_func expr_xform_extra,
/*@null@*/ void *expr_xform_extra_data, /*@null@*/ yasm__exprhead *eh);
-/* Simplifies the expression e as much as possible, eliminating extraneous
- * branches and simplifying integer-only subexpressions.
+/** Simplify an expression as much as possible. Eliminates extraneous
+ * branches and simplifies integer-only subexpressions. Simplified version
+ * of yasm_expr__level_tree().
+ * \param e expression
+ * \param cbd bytecode distance-calculation function
+ * \return Simplified expression.
*/
#define yasm_expr_simplify(e, cbd) \
yasm_expr__level_tree(e, 1, 1, cbd, NULL, NULL, NULL)
-/* Extracts a single symrec out of an expression, replacing it with the
- * symrec's value (if it's a label). Returns NULL if it's unable to extract a
- * symrec (too complex of expr, none present, etc).
+/** Extract a single symbol out of an expression. Replaces it with the
+ * symbol's value (if it's a label).
+ * \param ep expression (pointer to)
+ * \param calc_bc_dist bytecode distance-calculation function
+ * \return NULL if unable to extract a symbol (too complex of expr, none
+ * present, etc); otherwise returns the extracted symbol.
*/
/*@dependent@*/ /*@null@*/ yasm_symrec *yasm_expr_extract_symrec
(yasm_expr **ep, yasm_calc_bc_dist_func calc_bc_dist);
-/* Gets the integer value of e if the expression is just an integer. If the
- * expression is more complex (contains anything other than integers, ie
- * floats, non-valued labels, registers), returns NULL.
+/** Get the integer value of an expression if it's just an integer.
+ * \param ep expression (pointer to)
+ * \param calc_bc_dist bytecode distance-calculation function
+ * \return NULL if the expression is too complex (contains anything other than
+ * integers, ie floats, non-valued labels, registers); otherwise the
+ * intnum value of the expression.
*/
/*@dependent@*/ /*@null@*/ const yasm_intnum *yasm_expr_get_intnum
(yasm_expr **ep, /*@null@*/ yasm_calc_bc_dist_func calc_bc_dist);
-/* Gets the float value of e if the expression is just an float. If the
- * expression is more complex (contains anything other than floats, ie
- * integers, non-valued labels, registers), returns NULL.
+/** Get the floating point value of an expression if it's just an floatnum.
+ * \param ep expression (pointer to)
+ * \return NULL if the expression is too complex (contains anything other than
+ * floats, ie integers, non-valued labels, registers); otherwise the
+ * floatnum value of the expression.
*/
/*@dependent@*/ /*@null@*/ const yasm_floatnum *yasm_expr_get_floatnum
(yasm_expr **ep);
-/* Gets the symrec value of e if the expression is just an symbol. If the
- * expression is more complex, returns NULL. Simplifies the expr first if
- * simplify is nonzero.
+/** Get the symbol value of an expression if it's just a symbol.
+ * \param ep expression (pointer to)
+ * \param simplify if nonzero, simplify the expression first
+ * \return NULL if the expression is too complex; otherwise the symbol value of
+ * the expression.
*/
/*@dependent@*/ /*@null@*/ const yasm_symrec *yasm_expr_get_symrec
(yasm_expr **ep, int simplify);
-/* Gets the register value of e if the expression is just a register. If the
- * expression is more complex, returns NULL. Simplifies the expr first if
- * simplify is nonzero.
+/** Get the register value of an expression if it's just a register.
+ * \param ep expression (pointer to)
+ * \param simplify if nonzero, simplify the expression first
+ * \return NULL if the expression is too complex; otherwise the register value
+ * of the expression.
*/
/*@dependent@*/ /*@null@*/ const unsigned long *yasm_expr_get_reg
(yasm_expr **ep, int simplify);
-void yasm_expr_print(FILE *f, /*@null@*/ const yasm_expr *);
+/** Print an expression. For debugging purposes.
+ * \param f file
+ * \param e expression
+ */
+void yasm_expr_print(FILE *f, /*@null@*/ const yasm_expr *e);
#endif
-/* $IdPath$
- * Big and little endian file functions header file.
+/**
+ * \file file.h
+ * \brief YASM big and little endian file interface.
+ *
+ * $IdPath: yasm/libyasm/file.h,v 1.12 2003/03/13 06:54:19 peter Exp $
*
* Copyright (C) 2001 Peter Johnson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- * 1. Redistributions of source code must retain the above copyright
+ * - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
+ * - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
#ifndef YASM_FILE_H
#define YASM_FILE_H
-/* These functions only work properly if p is an (unsigned char *) */
-
+/** Write an 8-bit value to a buffer, incrementing buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 8-bit value
+ */
#define YASM_WRITE_8(ptr, val) \
*((ptr)++) = (unsigned char)((val) & 0xFF)
+/** Write a 16-bit value to a buffer in little endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_WRITE_16_L(ptr, val) \
do { \
*((ptr)++) = (unsigned char)((val) & 0xFF); \
*((ptr)++) = (unsigned char)(((val) >> 8) & 0xFF); \
} while (0)
+/** Write a 32-bit value to a buffer in little endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_WRITE_32_L(ptr, val) \
do { \
*((ptr)++) = (unsigned char)((val) & 0xFF); \
*((ptr)++) = (unsigned char)(((val) >> 24) & 0xFF); \
} while (0)
+/** Write a 16-bit value to a buffer in big endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_WRITE_16_B(ptr, val) \
do { \
*((ptr)++) = (unsigned char)(((val) >> 8) & 0xFF); \
*((ptr)++) = (unsigned char)((val) & 0xFF); \
} while (0)
+/** Write a 32-bit value to a buffer in big endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_WRITE_32_B(ptr, val) \
do { \
*((ptr)++) = (unsigned char)(((val) >> 24) & 0xFF); \
} while (0)
-/* Non-incrementing versions of the above. */
-
+/** Write an 8-bit value to a buffer. Does not increment buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 8-bit value
+ */
#define YASM_SAVE_8(ptr, val) \
*(ptr) = (unsigned char)((val) & 0xFF)
+/** Write a 16-bit value to a buffer in little endian. Does not increment
+ * buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_SAVE_16_L(ptr, val) \
do { \
*(ptr) = (unsigned char)((val) & 0xFF); \
*((ptr)+1) = (unsigned char)(((val) >> 8) & 0xFF); \
} while (0)
+/** Write a 32-bit value to a buffer in little endian. Does not increment
+ * buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_SAVE_32_L(ptr, val) \
do { \
*(ptr) = (unsigned char)((val) & 0xFF); \
*((ptr)+3) = (unsigned char)(((val) >> 24) & 0xFF); \
} while (0)
+/** Write a 16-bit value to a buffer in big endian. Does not increment buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_SAVE_16_B(ptr, val) \
do { \
*(ptr) = (unsigned char)(((val) >> 8) & 0xFF); \
*((ptr)+1) = (unsigned char)((val) & 0xFF); \
} while (0)
+/** Write a 32-bit value to a buffer in big endian. Does not increment buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_SAVE_32_B(ptr, val) \
do { \
*(ptr) = (unsigned char)(((val) >> 24) & 0xFF); \
*((ptr)+3) = (unsigned char)((val) & 0xFF); \
} while (0)
-/* Direct-to-file versions of the above. Using the above macros and a single
- * fwrite() will probably be faster than calling these functions many times.
- * These functions return 1 if the write was successful, 0 if not (so their
- * return values can be used like the return value from fwrite()).
+/** Direct-to-file version of YASM_SAVE_16_L().
+ * \note Using the macro multiple times with a single fwrite() call will
+ * probably be faster than calling this function many times.
+ * \param val 16-bit value
+ * \param f file
+ * \return 1 if the write was successful, 0 if not (just like fwrite()).
*/
-
size_t yasm_fwrite_16_l(unsigned short val, FILE *f);
+
+/** Direct-to-file version of YASM_SAVE_32_L().
+ * \note Using the macro multiple times with a single fwrite() call will
+ * probably be faster than calling this function many times.
+ * \param val 32-bit value
+ * \param f file
+ * \return 1 if the write was successful, 0 if not (just like fwrite()).
+ */
size_t yasm_fwrite_32_l(unsigned long val, FILE *f);
+
+/** Direct-to-file version of YASM_SAVE_16_B().
+ * \note Using the macro multiple times with a single fwrite() call will
+ * probably be faster than calling this function many times.
+ * \param val 16-bit value
+ * \param f file
+ * \return 1 if the write was successful, 0 if not (just like fwrite()).
+ */
size_t yasm_fwrite_16_b(unsigned short val, FILE *f);
-size_t yasm_fwrite_32_b(unsigned long val, FILE *f);
-/* Read/Load versions. val is the variable to receive the data. */
+/** Direct-to-file version of YASM_SAVE_32_B().
+ * \note Using the macro multiple times with a single fwrite() call will
+ * probably be faster than calling this function many times.
+ * \param val 32-bit value
+ * \param f file
+ * \return 1 if the write was successful, 0 if not (just like fwrite()).
+ */
+size_t yasm_fwrite_32_b(unsigned long val, FILE *f);
+/** Read an 8-bit value from a buffer, incrementing buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 8-bit value
+ */
#define YASM_READ_8(val, ptr) \
(val) = *((ptr)++) & 0xFF
+/** Read a 16-bit value from a buffer in little endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_READ_16_L(val, ptr) \
do { \
(val) = *((ptr)++) & 0xFF; \
(val) |= (*((ptr)++) & 0xFF) << 8; \
} while (0)
+/** Read a 32-bit value from a buffer in little endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_READ_32_L(val, ptr) \
do { \
(val) = *((ptr)++) & 0xFF; \
(val) |= (*((ptr)++) & 0xFF) << 24; \
} while (0)
+/** Read a 16-bit value from a buffer in big endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_READ_16_B(val, ptr) \
do { \
(val) = (*((ptr)++) & 0xFF) << 8; \
(val) |= *((ptr)++) & 0xFF; \
} while (0)
+/** Read a 32-bit value from a buffer in big endian, incrementing buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_READ_32_B(val, ptr) \
do { \
(val) = (*((ptr)++) & 0xFF) << 24; \
(val) |= *((ptr)++) & 0xFF; \
} while (0)
-/* Non-incrementing versions of the above. */
-
+/** Read an 8-bit value from a buffer. Does not increment buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 8-bit value
+ */
#define YASM_LOAD_8(val, ptr) \
(val) = *(ptr) & 0xFF
+/** Read a 16-bit value from a buffer in little endian. Does not increment
+ * buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_LOAD_16_L(val, ptr) \
do { \
(val) = *(ptr) & 0xFF; \
(val) |= (*((ptr)+1) & 0xFF) << 8; \
} while (0)
+/** Read a 32-bit value from a buffer in little endian. Does not increment
+ * buffer pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_LOAD_32_L(val, ptr) \
do { \
(val) = (unsigned long)(*(ptr) & 0xFF); \
(val) |= (unsigned long)((*((ptr)+3) & 0xFF) << 24); \
} while (0)
+/** Read a 16-bit value from a buffer in big endian. Does not increment buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 16-bit value
+ */
#define YASM_LOAD_16_B(val, ptr) \
do { \
(val) = (*(ptr) & 0xFF) << 8; \
(val) |= *((ptr)+1) & 0xFF; \
} while (0)
+/** Read a 32-bit value from a buffer in big endian. Does not increment buffer
+ * pointer.
+ * \note Only works properly if ptr is an (unsigned char *).
+ * \param ptr buffer
+ * \param val 32-bit value
+ */
#define YASM_LOAD_32_B(val, ptr) \
do { \
(val) = (unsigned long)((*(ptr) & 0xFF) << 24); \
-/* $IdPath$
- * Section header file
+/**
+ * \file section.h
+ * \brief YASM section interface.
+ *
+ * $IdPath: yasm/libyasm/section.h,v 1.36 2003/03/15 05:07:48 peter Exp $
*
* Copyright (C) 2001 Peter Johnson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- * 1. Redistributions of source code must retain the above copyright
+ * - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
+ * - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
/*@reldef@*/ STAILQ_HEAD(yasm_sectionhead, yasm_section);
#endif
+/** Create a new section list. A default section is created as the
+ * first section.
+ * \param headp pre-allocated section list head
+ * \param of object format in use
+ * \return Default section.
+ */
/*@dependent@*/ yasm_section *yasm_sections_initialize(yasm_sectionhead *headp,
yasm_objfmt *of);
+/** Create a new, or continue an existing, general section. The section is
+ * added to a section list if there's not already a section by that name.
+ * \param headp section list
+ * \param name section name
+ * \param start starting address (ignored if section already exists)
+ * \param res_only if nonzero, only space-reserving bytecodes are allowed in
+ * the section (ignored if section already exists)
+ * \param isnew output; set to nonzero if section did not already exist
+ * \param lindex line index of section declaration (ignored if section
+ * already exists)
+ * \return New section.
+ */
/*@dependent@*/ yasm_section *yasm_sections_switch_general
(yasm_sectionhead *headp, const char *name, unsigned long start,
int res_only, /*@out@*/ int *isnew, unsigned long lindex);
+/** Create a new absolute section. No checking is performed at creation to
+ * check for overlaps with other absolute sections.
+ * \param headp section list
+ * \param start starting address (expression)
+ * \return New section.
+ */
/*@dependent@*/ yasm_section *yasm_sections_switch_absolute
(yasm_sectionhead *headp, /*@keep@*/ yasm_expr *start);
+/** Determine if a section is absolute or general.
+ * \param sect section
+ * \return Nonzero if section is absolute.
+ */
int yasm_section_is_absolute(yasm_section *sect);
-/* Get and set optimizer flags */
+/** Get yasm_optimizer-specific flags. For yasm_optimizer use only.
+ * \param sect section
+ * \return Optimizer-specific flags.
+ */
unsigned long yasm_section_get_opt_flags(const yasm_section *sect);
+
+/** Set yasm_optimizer-specific flags. For yasm_optimizer use only.
+ * \param sect section
+ * \param opt_flags optimizer-specific flags.
+ */
void yasm_section_set_opt_flags(yasm_section *sect, unsigned long opt_flags);
+/** Get yasm_objfmt-specific data. For yasm_objfmt use only.
+ * \param sect section
+ * \return Object format-specific data.
+ */
+/*@dependent@*/ /*@null@*/ void *yasm_section_get_of_data(yasm_section *sect);
+
+/** Set yasm_objfmt-specific data. For yasm_objfmt use only.
+ * \caution Deletes any existing of_data.
+ * \param sect section
+ * \param of object format
+ * \param of_data object format-specific data.
+ */
void yasm_section_set_of_data(yasm_section *sect, yasm_objfmt *of,
/*@null@*/ /*@only@*/ void *of_data);
-/*@dependent@*/ /*@null@*/ void *yasm_section_get_of_data(yasm_section *sect);
+/** Delete (free allocated memory for) a section list. All sections in the
+ * section list and all bytecodes within those sections are also deleted.
+ * \param headp section list
+ */
void yasm_sections_delete(yasm_sectionhead *headp);
+/** Print a section list. For debugging purposes.
+ * \param f file
+ * \param indent_level indentation level
+ * \param headp section list
+ */
void yasm_sections_print(FILE *f, int indent_level,
const yasm_sectionhead *headp);
-/* Calls func for each section in the linked list of sections pointed to by
- * headp. The data pointer d is passed to each func call.
- *
- * Stops early (and returns func's return value) if func returns a nonzero
- * value. Otherwise returns 0.
+/** Traverses a section list, calling a function on each bytecode.
+ * \param headp bytecode list
+ * \param d data pointer passed to func on each call
+ * \param func function
+ * \return Stops early (and returns func's return value) if func returns a
+ * nonzero value; otherwise 0.
*/
int yasm_sections_traverse(yasm_sectionhead *headp, /*@null@*/ void *d,
int (*func) (yasm_section *sect,
/*@null@*/ void *d));
+/** Find a section based on its name.
+ * \param headp section list
+ * \param name section name
+ * \return Section matching name, or NULL if no match found.
+ */
/*@dependent@*/ /*@null@*/ yasm_section *yasm_sections_find_general
(yasm_sectionhead *headp, const char *name);
+/** Get bytecode list of a section.
+ * \param sect section
+ * \return Bytecode list.
+ */
/*@dependent@*/ yasm_bytecodehead *yasm_section_get_bytecodes
(yasm_section *sect);
+/** Get name of a section.
+ * \param sect section
+ * \return Section name, or NULL if section is absolute.
+ */
/*@observer@*/ /*@null@*/ const char *yasm_section_get_name
(const yasm_section *sect);
+/** Change starting address of a section.
+ * \param sect section
+ * \param start starting address
+ * \param lindex line index
+ */
void yasm_section_set_start(yasm_section *sect, unsigned long start,
unsigned long lindex);
+
+/** Get starting address of a section.
+ * \param sect section
+ * \return Starting address (may be a complex expression if section is
+ * absolute).
+ */
/*@observer@*/ const yasm_expr *yasm_section_get_start
(const yasm_section *sect);
void yasm_section_delete(/*@only@*/ yasm_section *sect);
+/** Print a section. For debugging purposes.
+ * \param f file
+ * \param indent_level indentation level
+ * \param sect section
+ * \param print_bcs if nonzero, print bytecodes within section
+ */
void yasm_section_print(FILE *f, int indent_level,
/*@null@*/ const yasm_section *sect, int print_bcs);
#endif
-/* $IdPath$
- * Symbol table handling header file
+/**
+ * \file symrec.h
+ * \brief YASM symbol table interface.
+ *
+ * $IdPath: yasm/libyasm/symrec.h,v 1.38 2003/03/13 06:54:19 peter Exp $
*
* Copyright (C) 2001 Michael Urman, Peter Johnson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- * 1. Redistributions of source code must retain the above copyright
+ * - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
+ * - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
#ifndef YASM_SYMREC_H
#define YASM_SYMREC_H
+/** Initialize symbol table internal data structures. */
void yasm_symrec_initialize(void);
+/** Clean up internal symbol table allocations. */
+void yasm_symrec_cleanup(void);
+
+/** Get a reference to (use) a symbol. The symbol does not necessarily need to
+ * be defined before it is used.
+ * \param name symbol name
+ * \param lindex line index where referenced
+ * \return Symbol (dependent pointer, do not free).
+ */
/*@dependent@*/ yasm_symrec *yasm_symrec_use(const char *name,
unsigned long lindex);
+
+/** Define a symbol as an EQU value.
+ * \param name symbol (EQU) name
+ * \param e EQU value (expression)
+ * \param lindex line index of EQU
+ * \return Symbol (dependent pointer, do not free).
+ */
/*@dependent@*/ yasm_symrec *yasm_symrec_define_equ
(const char *name, /*@keep@*/ yasm_expr *e, unsigned long lindex);
-/* in_table specifies if the label should be inserted into the symbol table.
- * All labels are memory managed internally.
+
+/** Define a symbol as a label.
+ * \param name symbol (label) name
+ * \param sect section containing label
+ * \param precbc bytecode preceding label (NULL if label is before first
+ * bytecode in section)
+ * \param in_table nonzero if the label should be inserted into the symbol
+ * table (some specially-generated ones should not be)
+ * \param lindex line index of label
+ * \return Symbol (dependent pointer, do not free).
*/
/*@dependent@*/ yasm_symrec *yasm_symrec_define_label
(const char *name, /*@dependent@*/ /*@null@*/ yasm_section *sect,
/*@dependent@*/ /*@null@*/ yasm_bytecode *precbc, int in_table,
unsigned long lindex);
+
+/** Declare external visibility of a symbol.
+ * \note Not all visibility combinations are allowed.
+ * \param name symbol name
+ * \param vis visibility
+ * \param lindex line index of visibility-setting
+ * \return Symbol (dependent pointer, do not free).
+ */
/*@dependent@*/ yasm_symrec *yasm_symrec_declare
(const char *name, yasm_sym_vis vis, unsigned long lindex);
+/** Get the name of a symbol.
+ * \param sym symbol
+ * \return Symbol name.
+ */
/*@observer@*/ const char *yasm_symrec_get_name(const yasm_symrec *sym);
+
+/** Get the visibility of a symbol.
+ * \param sym symbol
+ * \return Symbol visibility.
+ */
yasm_sym_vis yasm_symrec_get_visibility(const yasm_symrec *sym);
+/** Get EQU value of a symbol.
+ * \param sym symbol
+ * \return EQU value, or NULL if symbol is not an EQU or is not defined.
+ */
/*@observer@*/ /*@null@*/ const yasm_expr *yasm_symrec_get_equ
(const yasm_symrec *sym);
-/* Returns 0 if not a label or if EXTERN/COMMON (not defined in the file) */
+
+/** Dependent pointer to a section. */
typedef /*@dependent@*/ /*@null@*/ yasm_section *
yasm_symrec_get_label_sectionp;
+
+/** Dependent pointer to a bytecode. */
typedef /*@dependent@*/ /*@null@*/ yasm_bytecode *
yasm_symrec_get_label_bytecodep;
+
+/** Get the label location of a symbol.
+ * \param sym symbol
+ * \param sect section containing label (output)
+ * \param precbc bytecode preceding label (output); NULL if no preceding
+ * bytecode in section.
+ * \return 0 if not symbol is not a label or if the symbol's visibility is
+ * #YASM_SYM_EXTERN or #YASM_SYM_COMMON (not defined in the file).
+ */
int yasm_symrec_get_label(const yasm_symrec *sym,
/*@out@*/ yasm_symrec_get_label_sectionp *sect,
/*@out@*/ yasm_symrec_get_label_bytecodep *precbc);
-/* Get and set optimizer flags */
+/** Get yasm_optimizer-specific flags. For yasm_optimizer use only.
+ * \param sym symbol
+ * \return Optimizer-specific flags.
+ */
unsigned long yasm_symrec_get_opt_flags(const yasm_symrec *sym);
+
+/** Set yasm_optimizer-specific flags. For yasm_optimizer use only.
+ * \param sym symbol
+ * \param opt_flags optimizer-specific flags.
+ */
void yasm_symrec_set_opt_flags(yasm_symrec *sym, unsigned long opt_flags);
+/** Get yasm_objfmt-specific data. For yasm_objfmt use only.
+ * \param sym symbol
+ * \return Object format-specific data.
+ */
/*@dependent@*/ /*@null@*/ void *yasm_symrec_get_of_data(yasm_symrec *sym);
-/* Caution: deletes any existing of_data */
+/** Set yasm_objfmt-specific data. For yasm_objfmt use only.
+ * \caution Deletes any existing of_data.
+ * \param sym symbol
+ * \param of object format
+ * \param of_data object format-specific data.
+ */
void yasm_symrec_set_of_data(yasm_symrec *sym, yasm_objfmt *of,
/*@only@*/ /*@null@*/ void *of_data);
+/** Callback function for yasm_symrec_traverse().
+ * \param sym symbol
+ * \param d data passed into yasm_symrec_traverse()
+ * \return Nonzero to stop symbol traversal.
+ */
+typedef int (*yasm_symrec_traverse_callback)
+ (yasm_symrec *sym, /*@null@*/ void *d);
+
+/** Traverse all symbols in the symbol table.
+ * \param d data to pass to each call of callback function
+ * \param func callback function called on each symbol
+ * \return Nonzero value returned by callback function if it ever returned
+ * nonzero.
+ */
int /*@alt void@*/ yasm_symrec_traverse
- (/*@null@*/ void *d, int (*func) (yasm_symrec *sym, /*@null@*/ void *d));
+ (/*@null@*/ void *d, yasm_symrec_traverse_callback func);
+/** Finalize symbol table after parsing stage. Checks for symbols that are
+ * used but never defined or declared #YASM_SYM_EXTERN or #YASM_SYM_COMMON.
+ */
void yasm_symrec_parser_finalize(void);
-void yasm_symrec_cleanup(void);
-
+/** Print the symbol table. For debugging purposes.
+ * \param f file
+ * \param indent_level indentation level
+ */
void yasm_symrec_print_all(FILE *f, int indent_level);
+/** Print a symbol. For debugging purposes.
+ * \param f file
+ * \param indent_level indentation level
+ * \param sym symbol
+ */
void yasm_symrec_print(FILE *f, int indent_level, const yasm_symrec *sym);
+
#endif
-/* $IdPath$
+/**
+ * \file util.h
+ * \brief YASM utility functions.
+ *
+ * $IdPath: yasm/libyasm/util.h,v 1.50 2003/05/03 08:02:15 peter Exp $
+ *
* Includes standard headers and defines prototypes for replacement functions
* if needed. This is the *only* header file which should include other
* header files!
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- * 1. Redistributions of source code must retain the above copyright
+ * - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
+ * - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
#endif /*YASM_AUTOCONF_INTERNAL*/
+/** Sort an array using merge sort algorithm.
+ * \internal
+ * \param base base of array
+ * \param nmemb number of elements in array
+ * \param size size of each array element
+ * \param compar element comparison function
+ */
int yasm__mergesort(void *base, size_t nmemb, size_t size,
int (*compar)(const void *, const void *));
#define yasm__mergesort(a, b, c, d) mergesort(a, b, c, d)
#endif
+/** Separate string by delimiters.
+ * \internal
+ * \param stringp string
+ * \param delim set of 1 or more delimiters
+ * \return First/next substring.
+ */
/*@null@*/ char *yasm__strsep(char **stringp, const char *delim);
#if defined(YASM_AUTOCONF_INTERNAL) && defined(HAVE_STRSEP)
#define yasm__strsep(a, b) strsep(a, b)
#endif
+/** Compare two strings, ignoring case differences.
+ * \internal
+ * \param s1 string 1
+ * \param s2 string 2
+ * \return 0 if strings are equal, -1 if s1<s2, 1 if s1>s2.
+ */
int yasm__strcasecmp(const char *s1, const char *s2);
+
+/** Compare portion of two strings, ignoring case differences.
+ * \internal
+ * \param s1 string 1
+ * \param s2 string 2
+ * \param n maximum number of characters to compare
+ * \return 0 if strings are equal, -1 if s1<s2, 1 if s1>s2.
+ */
int yasm__strncasecmp(const char *s1, const char *s2, size_t n);
#ifdef YASM_AUTOCONF_INTERNAL
# endif
#endif
-/* strdup() implementation with error checking (using xmalloc). */
+/** strdup() implementation using yasm_xmalloc().
+ * \internal
+ * \param str string
+ * \return Newly allocated duplicate string.
+ */
/*@only@*/ char *yasm__xstrdup(const char *str);
+
+/** strndup() implementation using yasm_xmalloc().
+ * \internal
+ * \param str string
+ * \param len maximum number of characters to copy
+ * \return Newly allocated duplicate string.
+ */
/*@only@*/ char *yasm__xstrndup(const char *str, size_t len);
#endif /*YASM_INTERNAL*/
-/* Error-checking memory allocation routines. Default implementations in
- * xmalloc.c.
+/** Error-checking memory allocation. A default implementation is provided
+ * that calls yasm_fatal() on allocation errors.
+ * A replacement should \em never return NULL.
+ * \param size number of bytes to allocate
+ * \return Allocated memory block.
*/
extern /*@only@*/ /*@out@*/ void * (*yasm_xmalloc) (size_t size);
+
+/** Error-checking memory allocation (with clear-to-0). A default
+ * implementation is provided that calls yasm_fatal() on allocation errors.
+ * A replacement should \em never return NULL.
+ * \param size number of elements to allocate
+ * \param elsize size (in bytes) of each element
+ * \return Allocated and cleared memory block.
+ */
extern /*@only@*/ void * (*yasm_xcalloc) (size_t nelem, size_t elsize);
+
+/** Error-checking memory reallocation. A default implementation is provided
+ * that calls yasm_fatal() on allocation errors. A replacement should
+ * \em never return NULL.
+ * \param oldmem memory block to resize
+ * \param elsize new size, in bytes
+ * \return Re-allocated memory block.
+ */
extern /*@only@*/ void * (*yasm_xrealloc)
(/*@only@*/ /*@out@*/ /*@returned@*/ /*@null@*/ void *oldmem, size_t size)
/*@modifies oldmem@*/;
+
+/** Error-checking memory deallocation. A default implementation is provided
+ * that calls yasm_fatal() on allocation errors.
+ * \param p memory block to free
+ */
extern void (*yasm_xfree) (/*@only@*/ /*@out@*/ /*@null@*/ void *p)
/*@modifies p@*/;
d += d>>8; \
} while (0)
-/* Get the number of elements in an array. */
#ifndef NELEMS
+/** Get the number of elements in an array.
+ * \internal
+ * \param array array
+ * \return Number of elements.
+ */
#define NELEMS(array) (sizeof(array) / sizeof(array[0]))
#endif
-/* $IdPath$
- * Value/Parameter type definition
+/**
+ * \file valparam.h
+ * \brief YASM Value/Parameter type interface.
+ *
+ * $IdPath: yasm/libyasm/valparam.h,v 1.12 2003/03/16 23:53:31 peter Exp $
*
* Copyright (C) 2001 Peter Johnson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- * 1. Redistributions of source code must retain the above copyright
+ * - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
+ * - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
#define YASM_VALPARAM_H
#ifdef YASM_INTERNAL
+/** Value/parameter pair. \internal */
struct yasm_valparam {
- /*@reldef@*/ STAILQ_ENTRY(yasm_valparam) link;
- /*@owned@*/ /*@null@*/ char *val;
- /*@owned@*/ /*@null@*/ yasm_expr *param;
+ /*@reldef@*/ STAILQ_ENTRY(yasm_valparam) link; /**< Next pair in list */
+ /*@owned@*/ /*@null@*/ char *val; /**< Value */
+ /*@owned@*/ /*@null@*/ yasm_expr *param; /**< Parameter */
};
+
+/** Linked list of value/parameter pairs. \internal */
/*@reldef@*/ STAILQ_HEAD(yasm_valparamhead, yasm_valparam);
#endif
+/** Create a new valparam.
+ * \param v value
+ * \param p parameter
+ * \return Newly allocated valparam.
+ */
yasm_valparam *yasm_vp_new(/*@keep@*/ char *v, /*@keep@*/ yasm_expr *p);
+/** Initialize linked list of valparams.
+ * \param headp linked list
+ */
void yasm_vps_initialize(/*@out@*/ yasm_valparamhead *headp);
#ifdef YASM_INTERNAL
#define yasm_vps_initialize(headp) STAILQ_INIT(headp)
#endif
+
+/** Destroy (free allocated memory for) linked list of valparams.
+ * \param headp linked list
+ */
void yasm_vps_delete(yasm_valparamhead *headp);
+
+/** Append valparam to tail of linked list.
+ * \param headp linked list
+ * \param vp valparam
+ */
void yasm_vps_append(yasm_valparamhead *headp, /*@keep@*/ yasm_valparam *vp);
#ifdef YASM_INTERNAL
#define yasm_vps_append(headp, vp) do { \
} while(0)
#endif
+/** Get first valparam in linked list.
+ * \param headp linked list
+ * \return First valparam in linked list.
+ */
/*@null@*/ /*@dependent@*/ yasm_valparam *yasm_vps_first
(yasm_valparamhead *headp);
#ifdef YASM_INTERNAL
#define yasm_vps_first(headp) STAILQ_FIRST(headp)
#endif
+/** Get next valparam in linked list.
+ * \param cur previous valparam in linked list
+ * \return Next valparam in linked list.
+ */
/*@null@*/ /*@dependent@*/ yasm_valparam *yasm_vps_next(yasm_valparam *cur);
#ifdef YASM_INTERNAL
#define yasm_vps_next(cur) STAILQ_NEXT(cur, link)
+/** Iterate through linked list of valparams.
+ * \internal
+ * \param iter iterator variable
+ * \param headp linked list
+ */
#define yasm_vps_foreach(iter, headp) STAILQ_FOREACH(iter, headp, link)
#endif
+/** Print linked list of valparams. For debugging purposes.
+ * \param f file
+ * \param headp linked list
+ */
void yasm_vps_print(FILE *f, /*@null@*/ const yasm_valparamhead *headp);
#endif
-/* $IdPath$
+/**
+ * \file util.h
+ * \brief YASM utility functions.
+ *
+ * $IdPath: yasm/libyasm/util.h,v 1.50 2003/05/03 08:02:15 peter Exp $
+ *
* Includes standard headers and defines prototypes for replacement functions
* if needed. This is the *only* header file which should include other
* header files!
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- * 1. Redistributions of source code must retain the above copyright
+ * - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
+ * - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
#endif /*YASM_AUTOCONF_INTERNAL*/
+/** Sort an array using merge sort algorithm.
+ * \internal
+ * \param base base of array
+ * \param nmemb number of elements in array
+ * \param size size of each array element
+ * \param compar element comparison function
+ */
int yasm__mergesort(void *base, size_t nmemb, size_t size,
int (*compar)(const void *, const void *));
#define yasm__mergesort(a, b, c, d) mergesort(a, b, c, d)
#endif
+/** Separate string by delimiters.
+ * \internal
+ * \param stringp string
+ * \param delim set of 1 or more delimiters
+ * \return First/next substring.
+ */
/*@null@*/ char *yasm__strsep(char **stringp, const char *delim);
#if defined(YASM_AUTOCONF_INTERNAL) && defined(HAVE_STRSEP)
#define yasm__strsep(a, b) strsep(a, b)
#endif
+/** Compare two strings, ignoring case differences.
+ * \internal
+ * \param s1 string 1
+ * \param s2 string 2
+ * \return 0 if strings are equal, -1 if s1<s2, 1 if s1>s2.
+ */
int yasm__strcasecmp(const char *s1, const char *s2);
+
+/** Compare portion of two strings, ignoring case differences.
+ * \internal
+ * \param s1 string 1
+ * \param s2 string 2
+ * \param n maximum number of characters to compare
+ * \return 0 if strings are equal, -1 if s1<s2, 1 if s1>s2.
+ */
int yasm__strncasecmp(const char *s1, const char *s2, size_t n);
#ifdef YASM_AUTOCONF_INTERNAL
# endif
#endif
-/* strdup() implementation with error checking (using xmalloc). */
+/** strdup() implementation using yasm_xmalloc().
+ * \internal
+ * \param str string
+ * \return Newly allocated duplicate string.
+ */
/*@only@*/ char *yasm__xstrdup(const char *str);
+
+/** strndup() implementation using yasm_xmalloc().
+ * \internal
+ * \param str string
+ * \param len maximum number of characters to copy
+ * \return Newly allocated duplicate string.
+ */
/*@only@*/ char *yasm__xstrndup(const char *str, size_t len);
#endif /*YASM_INTERNAL*/
-/* Error-checking memory allocation routines. Default implementations in
- * xmalloc.c.
+/** Error-checking memory allocation. A default implementation is provided
+ * that calls yasm_fatal() on allocation errors.
+ * A replacement should \em never return NULL.
+ * \param size number of bytes to allocate
+ * \return Allocated memory block.
*/
extern /*@only@*/ /*@out@*/ void * (*yasm_xmalloc) (size_t size);
+
+/** Error-checking memory allocation (with clear-to-0). A default
+ * implementation is provided that calls yasm_fatal() on allocation errors.
+ * A replacement should \em never return NULL.
+ * \param size number of elements to allocate
+ * \param elsize size (in bytes) of each element
+ * \return Allocated and cleared memory block.
+ */
extern /*@only@*/ void * (*yasm_xcalloc) (size_t nelem, size_t elsize);
+
+/** Error-checking memory reallocation. A default implementation is provided
+ * that calls yasm_fatal() on allocation errors. A replacement should
+ * \em never return NULL.
+ * \param oldmem memory block to resize
+ * \param elsize new size, in bytes
+ * \return Re-allocated memory block.
+ */
extern /*@only@*/ void * (*yasm_xrealloc)
(/*@only@*/ /*@out@*/ /*@returned@*/ /*@null@*/ void *oldmem, size_t size)
/*@modifies oldmem@*/;
+
+/** Error-checking memory deallocation. A default implementation is provided
+ * that calls yasm_fatal() on allocation errors.
+ * \param p memory block to free
+ */
extern void (*yasm_xfree) (/*@only@*/ /*@out@*/ /*@null@*/ void *p)
/*@modifies p@*/;
d += d>>8; \
} while (0)
-/* Get the number of elements in an array. */
#ifndef NELEMS
+/** Get the number of elements in an array.
+ * \internal
+ * \param array array
+ * \return Number of elements.
+ */
#define NELEMS(array) (sizeof(array) / sizeof(array[0]))
#endif
projects / yasm / commitdiff