libyasm/dbgfmt.h

   1 /**
   2  * \file libyasm/dbgfmt.h
   3  * \brief YASM debug format interface.
   4  *
   5  * \license
   6  *  Copyright (C) 2002-2007  Peter Johnson
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *  - Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  *  - Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND OTHER CONTRIBUTORS ``AS IS''
  18  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR OTHER CONTRIBUTORS BE
  21  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27  * POSSIBILITY OF SUCH DAMAGE.
  28  * \endlicense
  29  */
  30 #ifndef YASM_DBGFMT_H
  31 #define YASM_DBGFMT_H
  32
  33 #ifndef YASM_DOXYGEN
  34 /** Base #yasm_dbgfmt structure.  Must be present as the first element in any
  35  * #yasm_dbgfmt implementation.
  36  */
  37 typedef struct yasm_dbgfmt_base {
  38     /** #yasm_dbgfmt_module implementation for this debug format. */
  39     const struct yasm_dbgfmt_module *module;
  40 } yasm_dbgfmt_base;
  41 #endif
  42
  43 /** Debug format module interface. */
  44 struct yasm_dbgfmt_module {
  45     /** One-line description of the debug format. */
  46     const char *name;
  47
  48     /** Keyword used to select debug format. */
  49     const char *keyword;
  50
  51     /** NULL-terminated list of directives.  NULL if none. */
  52     /*@null@*/ const yasm_directive *directives;
  53
  54     /** Create debug format.
  55      * Module-level implementation of yasm_dbgfmt_create().
  56      * The filenames are provided solely for informational purposes.
  57      * \param object        object
  58      * \return NULL if object format does not provide needed support.
  59      */
  60     /*@null@*/ /*@only@*/ yasm_dbgfmt * (*create) (yasm_object *object);
  61
  62     /** Module-level implementation of yasm_dbgfmt_destroy().
  63      * Call yasm_dbgfmt_destroy() instead of calling this function.
  64      */
  65     void (*destroy) (/*@only@*/ yasm_dbgfmt *dbgfmt);
  66
  67     /** Module-level implementation of yasm_dbgfmt_generate().
  68      * Call yasm_dbgfmt_generate() instead of calling this function.
  69      */
  70     void (*generate) (yasm_object *object, yasm_linemap *linemap,
  71                       yasm_errwarns *errwarns);
  72 };
  73
  74 /** Get the keyword used to select a debug format.
  75  * \param dbgfmt    debug format
  76  * \return keyword
  77  */
  78 const char *yasm_dbgfmt_keyword(const yasm_dbgfmt *dbgfmt);
  79
  80 /** Initialize debug output for use.  Must call before any other debug
  81  * format functions.  The filenames are provided solely for informational
  82  * purposes.
  83  * \param module        debug format module
  84  * \param object        object to generate debugging information for
  85  * \return NULL if object format does not provide needed support.
  86  */
  87 /*@null@*/ /*@only@*/ yasm_dbgfmt *yasm_dbgfmt_create
  88     (const yasm_dbgfmt_module *module, yasm_object *object);
  89
  90 /** Cleans up any allocated debug format memory.
  91  * \param dbgfmt        debug format
  92  */
  93 void yasm_dbgfmt_destroy(/*@only@*/ yasm_dbgfmt *dbgfmt);
  94
  95 /** Generate debugging information bytecodes.
  96  * \param object        object
  97  * \param linemap       virtual/physical line mapping
  98  * \param errwarns      error/warning set
  99  * \note Errors and warnings are stored into errwarns.
 100  */
 101 void yasm_dbgfmt_generate(yasm_object *object, yasm_linemap *linemap,
 102                           yasm_errwarns *errwarns);
 103
 104 #ifndef YASM_DOXYGEN
 105
 106 /* Inline macro implementations for dbgfmt functions */
 107
 108 #define yasm_dbgfmt_keyword(dbgfmt) \
 109     (((yasm_dbgfmt_base *)dbgfmt)->module->keyword)
 110
 111 #define yasm_dbgfmt_create(module, object) \
 112     module->create(object)
 113
 114 #define yasm_dbgfmt_destroy(dbgfmt) \
 115     ((yasm_dbgfmt_base *)dbgfmt)->module->destroy(dbgfmt)
 116 #define yasm_dbgfmt_generate(object, linemap, ews) \
 117     ((yasm_dbgfmt_base *)((object)->dbgfmt))->module->generate \
 118         (object, linemap, ews)
 119
 120 #endif
 121
 122 #endif