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 384