-/* $IdPath$
- * YASM object format module interface header file
+/**
+ * \file libyasm/objfmt.h
+ * \brief YASM object format module interface.
*
+ * \rcs
+ * $IdPath$
+ * \endrcs
+ *
+ * \license
* 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.
*
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
+ * \endlicense
*/
#ifndef YASM_OBJFMT_H
#define YASM_OBJFMT_H
-/* Interface to the object format module(s) */
+/** YASM object format interface. */
struct yasm_objfmt {
- /* one-line description of the format */
+ /** One-line description of the object format. */
const char *name;
- /* keyword used to select format on the command line */
+ /** Keyword used to select object format. */
const char *keyword;
- /* default output file extension (without the '.').
+ /** Default output file extension (without the '.').
* NULL means no extension, with no '.', while "" includes the '.'.
*/
/*@null@*/ const char *extension;
- /* default (starting) section name */
+ /** Default (starting) section name. */
const char *default_section_name;
- /* default (starting) x86 BITS setting */
+ /** Default (starting) x86 BITS setting. This only appies to the x86
+ * architecture; other architectures ignore this setting.
+ */
const unsigned char default_x86_mode_bits;
- /* NULL-terminated list of debugging formats that are valid to use with
- * this object format. The null debugging format (null_dbgfmt) should
- * always be in this list so it's possible to have no debugging output.
+ /** NULL-terminated list of debug format (yasm_dbgfmt) keywords that are
+ * valid to use with this object format. The null debug format
+ * (null_dbgfmt, "null") should always be in this list so it's possible to
+ * have no debug output.
*/
const char **dbgfmt_keywords;
- /* Default debugging format (set even if there's only one available to
+ /** Default debug format keyword (set even if there's only one available to
* use).
*/
const char *default_dbgfmt_keyword;
- /* Initializes object output. Must be called before any other object
- * format functions. Should NOT open the object file; the filenames are
- * provided solely for informational purposes.
+ /** Initialize object output for use. Must be called before any other
+ * object format functions. Should /not/ open the object file; the
+ * filenames are provided solely for informational purposes.
+ * \param in_filename main input filename (e.g. "file.asm")
+ * \param obj_filename object filename (e.g. "file.o")
+ * \param df debug format in use
+ * \param a architecture in use
*/
void (*initialize) (const char *in_filename, const char *obj_filename,
yasm_dbgfmt *df, yasm_arch *a);
- /* Write out (post-optimized) sections to the object file.
- * This function may call symrec functions as necessary (including
- * symrec_traverse) to retrieve symbolic information.
+ /** Write out (post-optimized) sections to the object file.
+ * This function may call yasm_symrec_* functions as necessary (including
+ * yasm_symrec_traverse()) to retrieve symbolic information.
+ * \param f output object file
+ * \param sections list of sections
+ * \param all_syms if nonzero, all symbols should be included in the
+ * object file
+ * \note The list of sections may include sections that will not actually
+ * be output into the object file.
*/
void (*output) (FILE *f, yasm_sectionhead *sections, int all_syms);
- /* Cleans up anything allocated by initialize.
- * May be NULL if not needed by the object format.
+ /** Cleans up anything allocated by initialize(). Function may be
+ * unimplemented (NULL) if not needed by the object format.
*/
void (*cleanup) (void);
- /* Switch object file sections. The first val of the valparams should
- * be the section name. Returns NULL if something's wrong, otherwise
- * returns the new section.
+ /** Switch object file sections. The first val of the valparams should
+ * be the section name. Calls yasm_section_switch() to actually change
+ * the active section.
+ * \param headp list of sections
+ * \param valparams value/parameters
+ * \param objext_valparams object format-specific value/parameters
+ * \param lindex line index (as from yasm_linemgr)
+ * \return NULL on error, otherwise new section.
*/
/*@observer@*/ /*@null@*/ yasm_section *
(*sections_switch)(yasm_sectionhead *headp,
/*@null@*/ yasm_valparamhead *objext_valparams,
unsigned long lindex);
- /* Object format-specific data handling functions for sections.
- * May be NULL if no data is ever allocated in sections_switch().
+ /** Delete yasm_section object format-specific data. Function may be
+ * unimplemented (NULL) if no data is ever allocated in sections_switch().
+ * \param data object format-specific data
*/
void (*section_data_delete)(/*@only@*/ void *data);
+
+ /** Print yasm_section object format-specific data. For debugging
+ * purposes. Function may be unimplemented (NULL) if no data is ever
+ * allocated in sections_switch() by the object format.
+ * \param f file
+ * \param indent_level indentation level
+ * \param data object format-specific data
+ */
void (*section_data_print)(FILE *f, int indent_level, void *data);
- /* These functions should call symrec_set_of_data() to store data.
- * May be NULL if objfmt doesn't care about such declarations.
+ /** Declare an "extern" (importing from another module) symbol. Should
+ * call yasm_symrec_set_of_data() to store data. Function may be
+ * unimplemented (NULL) if object format doesn't care about such a
+ * declaration.
+ * \param sym symbol
+ * \param objext_valparams object format-specific value/paramaters
+ * \param lindex line index (from yasm_linemgr)
*/
void (*extern_declare)(yasm_symrec *sym,
/*@null@*/ yasm_valparamhead *objext_valparams,
unsigned long lindex);
+
+ /** Declare a "global" (exporting to other modules) symbol. Should call
+ * yasm_symrec_set_of_data() to store data. Function may be unimplemented
+ * (NULL) if object format doesn't care about such a declaration.
+ * \param sym symbol
+ * \param objext_valparams object format-specific value/paramaters
+ * \param lindex line index (from yasm_linemgr)
+ */
void (*global_declare)(yasm_symrec *sym,
/*@null@*/ yasm_valparamhead *objext_valparams,
unsigned long lindex);
+
+ /** Declare a "common" (shared space with other modules) symbol. Should
+ * call yasm_symrec_set_of_data() to store data. Function may be
+ * unimplemented (NULL) if object format doesn't care about such a
+ * declaration.
+ * \param sym symbol
+ * \param size common data size
+ * \param objext_valparams object format-specific value/paramaters
+ * \param lindex line index (from yasm_linemgr)
+ */
void (*common_declare)(yasm_symrec *sym, /*@only@*/ yasm_expr *size,
/*@null@*/ yasm_valparamhead *objext_valparams,
unsigned long lindex);
- /* May be NULL if symrec_set_of_data() is never called. */
+ /** Delete object format-specific symbol data. Function may be
+ * unimplemented (NULL) if yasm_symrec_set_of_data() is never called by the
+ * object format.
+ * \param data object format-specific data
+ */
void (*symrec_data_delete)(/*@only@*/ void *data);
+
+ /** Print object format-specific symbol data. For debugging purposes.
+ * Function may be unimplemented (NULL) if yasm_symrec_set_of_data() is
+ * never called by the object format.
+ * \param f file
+ * \param indent_level indentation level
+ * \param data object format-specific data
+ */
void (*symrec_data_print)(FILE *f, int indent_level, void *data);
- /* Object format-specific directive support. Returns 1 if directive was
- * not recognized. Returns 0 if directive was recognized, even if it
- * wasn't valid.
+ /** Handle object format-specific directives.
+ * \param name directive name
+ * \param valparams value/parameters
+ * \param objext_valparams object format-specific value/parameters
+ * \param headp list of sections
+ * \param lindex line index (as from yasm_linemgr)
+ * \return Nonzero if directive was not recognized; 0 if directive was
+ * recognized, even if it wasn't valid.
*/
int (*directive)(const char *name, yasm_valparamhead *valparams,
/*@null@*/ yasm_valparamhead *objext_valparams,
yasm_sectionhead *headp, unsigned long lindex);
- /* Bytecode objfmt data (BC_OBJFMT_DATA) handling functions.
- * May be NULL if no BC_OBJFMT_DATA is ever allocated by the object format.
+ /** Delete object format-specific bytecode data (YASM_BC_OBJFMT_DATA).
+ * Function may be unimplemented (NULL) if no YASM_BC_OBJFMT_DATA is ever
+ * allocated by the object format.
+ * \param type object format-specific bytecode type
+ * \param data object format-specific data
*/
void (*bc_objfmt_data_delete)(unsigned int type, /*@only@*/ void *data);
+
+ /** Print object format-specific bytecode data (YASM_BC_OBJFMT_DATA). For
+ * debugging purposes. Function may be unimplemented (NULL) if no
+ * YASM_BC_OBJFMT_DATA is ever allocated by the object format.
+ * \param f file
+ * \param indent_level indentation level
+ * \param type object format-specific bytecode type
+ * \param data object format-specific data
+ */
void (*bc_objfmt_data_print)(FILE *f, int indent_level, unsigned int type,
const void *data);
};
projects / yasm / commitdiff