libyasm/section.h

   1 /**
   2  * \file libyasm/section.h
   3  * \brief YASM section interface.
   4  *
   5  * \license
   6  *  Copyright (C) 2001-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_SECTION_H
  31 #define YASM_SECTION_H
  32
  33 #ifndef YASM_LIB_DECL
  34 #define YASM_LIB_DECL
  35 #endif
  36
  37 /** Basic YASM relocation.  Object formats will need to extend this
  38  * structure with additional fields for relocation type, etc.
  39  */
  40 typedef struct yasm_reloc yasm_reloc;
  41
  42 struct yasm_reloc {
  43     /*@reldef@*/ STAILQ_ENTRY(yasm_reloc) link; /**< Link to next reloc */
  44     yasm_intnum *addr;          /**< Offset (address) within section */
  45     /*@dependent@*/ yasm_symrec *sym;       /**< Relocated symbol */
  46 };
  47
  48 /** An object.  This is the internal representation of an object file. */
  49 struct yasm_object {
  50     /*@owned@*/ char *src_filename;     /**< Source filename */
  51     /*@owned@*/ char *obj_filename;     /**< Object filename */
  52
  53     /*@owned@*/ yasm_symtab *symtab;    /**< Symbol table */
  54     /*@owned@*/ yasm_arch *arch;        /**< Target architecture */
  55     /*@owned@*/ yasm_objfmt *objfmt;    /**< Object format */
  56     /*@owned@*/ yasm_dbgfmt *dbgfmt;    /**< Debug format */
  57
  58     /** Currently active section.  Used by some directives.  NULL if no
  59      * section active.
  60      */
  61     /*@dependent@*/ /*@null@*/ yasm_section *cur_section;
  62
  63     /** Linked list of sections. */
  64     /*@reldef@*/ STAILQ_HEAD(yasm_sectionhead, yasm_section) sections;
  65
  66     /** Directives, organized as two level HAMT; first level is parser,
  67      * second level is directive name.
  68      */
  69     /*@owned@*/ struct HAMT *directives;
  70
  71     /** Prefix prepended to externally-visible symbols (empty string if none) */
  72     /*@owned@*/ char *global_prefix;
  73
  74     /** Suffix appended to externally-visible symbols (empty string if none) */
  75     /*@owned@*/ char *global_suffix;
  76 };
  77
  78 /** Create a new object.  A default section is created as the first section.
  79  * An empty symbol table (yasm_symtab) and line mapping (yasm_linemap) are
  80  * automatically created.
  81  * \param src_filename  source filename (e.g. "file.asm")
  82  * \param obj_filename  object filename (e.g. "file.o")
  83  * \param arch          architecture
  84  * \param objfmt_module object format module
  85  * \param dbgfmt_module debug format module
  86  * \return Newly allocated object, or NULL on error.
  87  */
  88 YASM_LIB_DECL
  89 /*@null@*/ /*@only@*/ yasm_object *yasm_object_create
  90     (const char *src_filename, const char *obj_filename,
  91      /*@kept@*/ yasm_arch *arch,
  92      const yasm_objfmt_module *objfmt_module,
  93      const yasm_dbgfmt_module *dbgfmt_module);
  94
  95 /** Create a new, or continue an existing, general section.  The section is
  96  * added to the object if there's not already a section by that name.
  97  * \param object    object
  98  * \param name      section name
  99  * \param align     alignment in bytes (0 if none)
 100  * \param code      if nonzero, section is intended to contain code
 101  *                  (e.g. alignment should be made with NOP instructions, not 0)
 102  * \param res_only  if nonzero, only space-reserving bytecodes are allowed in
 103  *                  the section (ignored if section already exists)
 104  * \param isnew     output; set to nonzero if section did not already exist
 105  * \param line      virtual line of section declaration (ignored if section
 106  *                  already exists)
 107  * \return New section.
 108  */
 109 YASM_LIB_DECL
 110 /*@dependent@*/ yasm_section *yasm_object_get_general
 111     (yasm_object *object, const char *name, unsigned long align, int code,
 112      int res_only, /*@out@*/ int *isnew, unsigned long line);
 113
 114 /** Handle a directive.  Passed down to object format, debug format, or
 115  * architecture as appropriate.
 116  * \param object                object
 117  * \param name                  directive name
 118  * \param parser                parser keyword
 119  * \param valparams             value/parameters
 120  * \param objext_valparams      "object format-specific" value/parameters
 121  * \param line                  virtual line (from yasm_linemap)
 122  * \return 0 if directive recognized, nonzero if unrecognized.
 123  */
 124 YASM_LIB_DECL
 125 int yasm_object_directive(yasm_object *object, const char *name,
 126                           const char *parser, yasm_valparamhead *valparams,
 127                           yasm_valparamhead *objext_valparams,
 128                           unsigned long line);
 129
 130 /** Delete (free allocated memory for) an object.  All sections in the
 131  * object and all bytecodes within those sections are also deleted.
 132  * \param object        object
 133  */
 134 YASM_LIB_DECL
 135 void yasm_object_destroy(/*@only@*/ yasm_object *object);
 136
 137 /** Print an object.  For debugging purposes.
 138  * \param object        object
 139  * \param f             file
 140  * \param indent_level  indentation level
 141  */
 142 YASM_LIB_DECL
 143 void yasm_object_print(const yasm_object *object, FILE *f, int indent_level);
 144
 145 /** Finalize an object after parsing.
 146  * \param object        object
 147  * \param errwarns      error/warning set
 148  * \note Errors/warnings are stored into errwarns.
 149  */
 150 YASM_LIB_DECL
 151 void yasm_object_finalize(yasm_object *object, yasm_errwarns *errwarns);
 152
 153 /** Traverses all sections in an object, calling a function on each section.
 154  * \param object        object
 155  * \param d             data pointer passed to func on each call
 156  * \param func          function
 157  * \return Stops early (and returns func's return value) if func returns a
 158  *         nonzero value; otherwise 0.
 159  */
 160 YASM_LIB_DECL
 161 int yasm_object_sections_traverse
 162     (yasm_object *object, /*@null@*/ void *d,
 163      int (*func) (yasm_section *sect, /*@null@*/ void *d));
 164
 165 /** Find a general section in an object, based on its name.
 166  * \param object        object
 167  * \param name          section name
 168  * \return Section matching name, or NULL if no match found.
 169  */
 170 YASM_LIB_DECL
 171 /*@dependent@*/ /*@null@*/ yasm_section *yasm_object_find_general
 172     (yasm_object *object, const char *name);
 173
 174 /** Change the source filename for an object.
 175  * \param object        object
 176  * \param src_filename  new source filename (e.g. "file.asm")
 177  */
 178 YASM_LIB_DECL
 179 void yasm_object_set_source_fn(yasm_object *object, const char *src_filename);
 180
 181 /** Change the prefix used for externally-visible symbols.
 182  * \param object        object
 183  * \param prefix        new prefix
 184  */
 185 YASM_LIB_DECL
 186 void yasm_object_set_global_prefix(yasm_object *object, const char *prefix);
 187
 188 /** Change the suffix used for externally-visible symbols.
 189  * \param object        object
 190  * \param suffix        new suffix
 191  */
 192 YASM_LIB_DECL
 193 void yasm_object_set_global_suffix(yasm_object *object, const char *suffix);
 194
 195 /** Optimize an object.  Takes the unoptimized object and optimizes it.
 196  * If successful, the object is ready for output to an object file.
 197  * \param object        object
 198  * \param errwarns      error/warning set
 199  * \note Optimization failures are stored into errwarns.
 200  */
 201 YASM_LIB_DECL
 202 void yasm_object_optimize(yasm_object *object, yasm_errwarns *errwarns);
 203
 204 /** Determine if a section is flagged to contain code.
 205  * \param sect      section
 206  * \return Nonzero if section is flagged to contain code.
 207  */
 208 YASM_LIB_DECL
 209 int yasm_section_is_code(yasm_section *sect);
 210
 211 /** Get yasm_optimizer-specific flags.  For yasm_optimizer use only.
 212  * \param sect      section
 213  * \return Optimizer-specific flags.
 214  */
 215 YASM_LIB_DECL
 216 unsigned long yasm_section_get_opt_flags(const yasm_section *sect);
 217
 218 /** Set yasm_optimizer-specific flags.  For yasm_optimizer use only.
 219  * \param sect      section
 220  * \param opt_flags optimizer-specific flags.
 221  */
 222 YASM_LIB_DECL
 223 void yasm_section_set_opt_flags(yasm_section *sect, unsigned long opt_flags);
 224
 225 /** Determine if a section was declared as the "default" section (e.g. not
 226  * created through a section directive).
 227  * \param sect      section
 228  * \return Nonzero if section was declared as default.
 229  */
 230 YASM_LIB_DECL
 231 int yasm_section_is_default(const yasm_section *sect);
 232
 233 /** Set section "default" flag to a new value.
 234  * \param sect      section
 235  * \param def       new value of default flag
 236  */
 237 YASM_LIB_DECL
 238 void yasm_section_set_default(yasm_section *sect, int def);
 239
 240 /** Get object owner of a section.
 241  * \param sect      section
 242  * \return Object this section is a part of.
 243  */
 244 YASM_LIB_DECL
 245 yasm_object *yasm_section_get_object(const yasm_section *sect);
 246
 247 /** Get assocated data for a section and data callback.
 248  * \param sect      section
 249  * \param callback  callback used when adding data
 250  * \return Associated data (NULL if none).
 251  */
 252 YASM_LIB_DECL
 253 /*@dependent@*/ /*@null@*/ void *yasm_section_get_data
 254     (yasm_section *sect, const yasm_assoc_data_callback *callback);
 255
 256 /** Add associated data to a section.
 257  * \attention Deletes any existing associated data for that data callback.
 258  * \param sect      section
 259  * \param callback  callback
 260  * \param data      data to associate
 261  */
 262 YASM_LIB_DECL
 263 void yasm_section_add_data(yasm_section *sect,
 264                            const yasm_assoc_data_callback *callback,
 265                            /*@null@*/ /*@only@*/ void *data);
 266
 267 /** Add a relocation to a section.
 268  * \param sect          section
 269  * \param reloc         relocation
 270  * \param destroy_func  function that can destroy the relocation
 271  * \note Does not make a copy of reloc.  The same destroy_func must be
 272  * used for all relocations in a section or an internal error will occur.
 273  * The section will destroy the relocation address; it is the caller's
 274  * responsibility to destroy any other allocated data.
 275  */
 276 YASM_LIB_DECL
 277 void yasm_section_add_reloc(yasm_section *sect, yasm_reloc *reloc,
 278     void (*destroy_func) (/*@only@*/ void *reloc));
 279
 280 /** Get the first relocation for a section.
 281  * \param sect          section
 282  * \return First relocation for section.  NULL if no relocations.
 283  */
 284 YASM_LIB_DECL
 285 /*@null@*/ yasm_reloc *yasm_section_relocs_first(yasm_section *sect);
 286
 287 /** Get the next relocation for a section.
 288  * \param reloc         previous relocation
 289  * \return Next relocation for section.  NULL if no more relocations.
 290  */
 291 /*@null@*/ yasm_reloc *yasm_section_reloc_next(yasm_reloc *reloc);
 292 #ifndef YASM_DOXYGEN
 293 #define yasm_section_reloc_next(x)      STAILQ_NEXT((x), link)
 294 #endif
 295
 296 /** Get the basic relocation information for a relocation.
 297  * \param reloc         relocation
 298  * \param addrp         address of relocation within section (returned)
 299  * \param symp          relocated symbol (returned)
 300  */
 301 YASM_LIB_DECL
 302 void yasm_reloc_get(yasm_reloc *reloc, yasm_intnum **addrp,
 303                     /*@dependent@*/ yasm_symrec **symp);
 304
 305 /** Get the first bytecode in a section.
 306  * \param sect          section
 307  * \return First bytecode in section (at least one empty bytecode is always
 308  *         present).
 309  */
 310 YASM_LIB_DECL
 311 yasm_bytecode *yasm_section_bcs_first(yasm_section *sect);
 312
 313 /** Get the last bytecode in a section.
 314  * \param sect          section
 315  * \return Last bytecode in section (at least one empty bytecode is always
 316  *         present).
 317  */
 318 YASM_LIB_DECL
 319 yasm_bytecode *yasm_section_bcs_last(yasm_section *sect);
 320
 321 /** Add bytecode to the end of a section.
 322  * \note Does not make a copy of bc; so don't pass this function static or
 323  *       local variables, and discard the bc pointer after calling this
 324  *       function.
 325  * \param sect          section
 326  * \param bc            bytecode (may be NULL)
 327  * \return If bytecode was actually appended (it wasn't NULL or empty), the
 328  *         bytecode; otherwise NULL.
 329  */
 330 YASM_LIB_DECL
 331 /*@only@*/ /*@null@*/ yasm_bytecode *yasm_section_bcs_append
 332     (yasm_section *sect,
 333      /*@returned@*/ /*@only@*/ /*@null@*/ yasm_bytecode *bc);
 334
 335 /** Traverses all bytecodes in a section, calling a function on each bytecode.
 336  * \param sect      section
 337  * \param errwarns  error/warning set (may be NULL)
 338  * \param d         data pointer passed to func on each call (may be NULL)
 339  * \param func      function
 340  * \return Stops early (and returns func's return value) if func returns a
 341  *         nonzero value; otherwise 0.
 342  * \note If errwarns is non-NULL, yasm_errwarn_propagate() is called after
 343  *       each call to func (with the bytecode's line number).
 344  */
 345 YASM_LIB_DECL
 346 int yasm_section_bcs_traverse
 347     (yasm_section *sect, /*@null@*/ yasm_errwarns *errwarns,
 348      /*@null@*/ void *d, int (*func) (yasm_bytecode *bc, /*@null@*/ void *d));
 349
 350 /** Get name of a section.
 351  * \param   sect    section
 352  * \return Section name.
 353  */
 354 YASM_LIB_DECL
 355 /*@observer@*/ const char *yasm_section_get_name(const yasm_section *sect);
 356
 357 /** Change alignment of a section.
 358  * \param sect      section
 359  * \param align     alignment in bytes
 360  * \param line      virtual line
 361  */
 362 YASM_LIB_DECL
 363 void yasm_section_set_align(yasm_section *sect, unsigned long align,
 364                             unsigned long line);
 365
 366 /** Get alignment of a section.
 367  * \param sect      section
 368  * \return Alignment in bytes (0 if none).
 369  */
 370 YASM_LIB_DECL
 371 unsigned long yasm_section_get_align(const yasm_section *sect);
 372
 373 /** Print a section.  For debugging purposes.
 374  * \param f             file
 375  * \param indent_level  indentation level
 376  * \param sect          section
 377  * \param print_bcs     if nonzero, print bytecodes within section
 378  */
 379 YASM_LIB_DECL
 380 void yasm_section_print(/*@null@*/ const yasm_section *sect, FILE *f,
 381                         int indent_level, int print_bcs);
 382
 383 #endif