From: Peter Johnson Date: Sun, 4 May 2003 20:28:28 +0000 (-0000) Subject: Comment for Doxygen documentation generation. Comment-only changes. X-Git-Tag: v0.2.2~3^2~14 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d710166b48e8b422ba55e04f6a992ea6a4a7e4b7;p=yasm Comment for Doxygen documentation generation. Comment-only changes. svn path=/trunk/yasm/; revision=939 --- diff --git a/libyasm/expr.h b/libyasm/expr.h index 674135da..e04767c3 100644 --- a/libyasm/expr.h +++ b/libyasm/expr.h @@ -1,14 +1,17 @@ -/* $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. * @@ -27,94 +30,189 @@ #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 diff --git a/libyasm/file.h b/libyasm/file.h index f02a1351..97969d07 100644 --- a/libyasm/file.h +++ b/libyasm/file.h @@ -1,14 +1,17 @@ -/* $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. * @@ -27,17 +30,32 @@ #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); \ @@ -46,12 +64,24 @@ *((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); \ @@ -61,17 +91,32 @@ } 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); \ @@ -80,12 +125,24 @@ *((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); \ @@ -94,28 +151,68 @@ *((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; \ @@ -124,12 +221,24 @@ size_t yasm_fwrite_32_b(unsigned long val, FILE *f); (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; \ @@ -138,17 +247,32 @@ size_t yasm_fwrite_32_b(unsigned long val, FILE *f); (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); \ @@ -157,12 +281,24 @@ size_t yasm_fwrite_32_b(unsigned long val, FILE *f); (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); \ diff --git a/libyasm/section.h b/libyasm/section.h index 7f351fb6..e409f530 100644 --- a/libyasm/section.h +++ b/libyasm/section.h @@ -1,14 +1,17 @@ -/* $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. * @@ -31,57 +34,144 @@ /*@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 diff --git a/libyasm/symrec.h b/libyasm/symrec.h index b8238187..cfc292ec 100644 --- a/libyasm/symrec.h +++ b/libyasm/symrec.h @@ -1,14 +1,17 @@ -/* $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. * @@ -27,54 +30,154 @@ #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 diff --git a/libyasm/util.h b/libyasm/util.h index e77fcc5e..71464ed2 100644 --- a/libyasm/util.h +++ b/libyasm/util.h @@ -1,4 +1,9 @@ -/* $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! @@ -8,9 +13,9 @@ * 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. * @@ -101,6 +106,13 @@ #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 *)); @@ -108,13 +120,33 @@ int yasm__mergesort(void *base, size_t nmemb, size_t size, #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 s1s2. + */ 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 s1s2. + */ int yasm__strncasecmp(const char *s1, const char *s2, size_t n); #ifdef YASM_AUTOCONF_INTERNAL @@ -158,20 +190,55 @@ int yasm__strncasecmp(const char *s1, const char *s2, size_t n); # 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@*/; @@ -200,8 +267,12 @@ extern void (*yasm_xfree) (/*@only@*/ /*@out@*/ /*@null@*/ void *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 diff --git a/libyasm/valparam.h b/libyasm/valparam.h index 34f282d3..d97c8980 100644 --- a/libyasm/valparam.h +++ b/libyasm/valparam.h @@ -1,14 +1,17 @@ -/* $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. * @@ -28,21 +31,41 @@ #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 { \ @@ -51,19 +74,36 @@ void yasm_vps_append(yasm_valparamhead *headp, /*@keep@*/ yasm_valparam *vp); } 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 diff --git a/util.h b/util.h index e77fcc5e..71464ed2 100644 --- a/util.h +++ b/util.h @@ -1,4 +1,9 @@ -/* $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! @@ -8,9 +13,9 @@ * 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. * @@ -101,6 +106,13 @@ #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 *)); @@ -108,13 +120,33 @@ int yasm__mergesort(void *base, size_t nmemb, size_t size, #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 s1s2. + */ 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 s1s2. + */ int yasm__strncasecmp(const char *s1, const char *s2, size_t n); #ifdef YASM_AUTOCONF_INTERNAL @@ -158,20 +190,55 @@ int yasm__strncasecmp(const char *s1, const char *s2, size_t n); # 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@*/; @@ -200,8 +267,12 @@ extern void (*yasm_xfree) (/*@only@*/ /*@out@*/ /*@null@*/ void *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