libyasm/bytecode.h

   1 /**
   2  * \file libyasm/bytecode.h
   3  * \brief YASM bytecode 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_BYTECODE_H
  31 #define YASM_BYTECODE_H
  32
  33 #ifndef YASM_LIB_DECL
  34 #define YASM_LIB_DECL
  35 #endif
  36
  37 /** A data value (opaque type). */
  38 typedef struct yasm_dataval yasm_dataval;
  39 /** A list of data values. */
  40 typedef struct yasm_datavalhead yasm_datavalhead;
  41
  42 /** Linked list of data values. */
  43 /*@reldef@*/ STAILQ_HEAD(yasm_datavalhead, yasm_dataval);
  44
  45 /** Add a dependent span for a bytecode.
  46  * \param add_span_data add_span_data passed into bc_calc_len()
  47  * \param bc            bytecode containing span
  48  * \param id            non-zero identifier for span; may be any non-zero value
  49  *                      if <0, expand is called for any change;
  50  *                      if >0, expand is only called when exceeds threshold
  51  * \param value         dependent value for bytecode expansion
  52  * \param neg_thres     negative threshold for long/short decision
  53  * \param pos_thres     positive threshold for long/short decision
  54  */
  55 typedef void (*yasm_bc_add_span_func)
  56     (void *add_span_data, yasm_bytecode *bc, int id, const yasm_value *value,
  57      long neg_thres, long pos_thres);
  58
  59 /** Bytecode callback structure.  Any implementation of a specific bytecode
  60  * must implement these functions and this callback structure.  The bytecode
  61  * implementation-specific data is stored in #yasm_bytecode.contents.
  62  */
  63 typedef struct yasm_bytecode_callback {
  64     /** Destroys the implementation-specific data.
  65      * Called from yasm_bc_destroy().
  66      * \param contents  #yasm_bytecode.contents
  67      */
  68     void (*destroy) (/*@only@*/ void *contents);
  69
  70     /** Prints the implementation-specific data (for debugging purposes).
  71      * Called from yasm_bc_print().
  72      * \param contents      #yasm_bytecode.contents
  73      * \param f             file
  74      * \param indent_level  indentation level
  75      */
  76     void (*print) (const void *contents, FILE *f, int indent_level);
  77
  78     /** Finalizes the bytecode after parsing.  Called from yasm_bc_finalize().
  79      * A generic fill-in for this is yasm_bc_finalize_common().
  80      * \param bc            bytecode
  81      * \param prev_bc       bytecode directly preceding bc
  82      */
  83     void (*finalize) (yasm_bytecode *bc, yasm_bytecode *prev_bc);
  84
  85     /** Return elements size of a data bytecode.
  86      * This function should return the size of each elements of a data
  87      * bytecode, for proper dereference of symbols attached to it.
  88      * \param bc            bytecode
  89      * \return 0 if element size is unknown.
  90      */
  91     int (*elem_size) (yasm_bytecode *bc);
  92
  93     /** Calculates the minimum size of a bytecode.
  94      * Called from yasm_bc_calc_len().
  95      * A generic fill-in for this is yasm_bc_calc_len_common(), but as this
  96      * function internal errors when called, be very careful when using it!
  97      * This function should simply add to bc->len and not set it directly
  98      * (it's initialized by yasm_bc_calc_len() prior to passing control to
  99      * this function).
 100      *
 101      * \param bc            bytecode
 102      * \param add_span      function to call to add a span
 103      * \param add_span_data extra data to be passed to add_span function
 104      * \return 0 if no error occurred, nonzero if there was an error
 105      *         recognized (and output) during execution.
 106      * \note May store to bytecode updated expressions.
 107      */
 108     int (*calc_len) (yasm_bytecode *bc, yasm_bc_add_span_func add_span,
 109                      void *add_span_data);
 110
 111     /** Recalculates the bytecode's length based on an expanded span length.
 112      * Called from yasm_bc_expand().
 113      * A generic fill-in for this is yasm_bc_expand_common(), but as this
 114      * function internal errors when called, if used, ensure that calc_len()
 115      * never adds a span.
 116      * This function should simply add to bc->len to increase the length by
 117      * a delta amount.
 118      * \param bc            bytecode
 119      * \param span          span ID (as given to add_span in calc_len)
 120      * \param old_val       previous span value
 121      * \param new_val       new span value
 122      * \param neg_thres     negative threshold for long/short decision
 123      *                      (returned)
 124      * \param pos_thres     positive threshold for long/short decision
 125      *                      (returned)
 126      * \return 0 if bc no longer dependent on this span's length, negative if
 127      *         there was an error recognized (and output) during execution,
 128      *         and positive if bc size may increase for this span further
 129      *         based on the new negative and positive thresholds returned.
 130      * \note May store to bytecode updated expressions.
 131      */
 132     int (*expand) (yasm_bytecode *bc, int span, long old_val, long new_val,
 133                    /*@out@*/ long *neg_thres, /*@out@*/ long *pos_thres);
 134
 135     /** Convert a bytecode into its byte representation.
 136      * Called from yasm_bc_tobytes().
 137      * A generic fill-in for this is yasm_bc_tobytes_common(), but as this
 138      * function internal errors when called, be very careful when using it!
 139      * \param bc            bytecode
 140      * \param bufp          byte representation destination buffer;
 141      *                      should be incremented as it's written to,
 142      *                      so that on return its delta from the
 143      *                      passed-in buf matches the bytecode length
 144      *                      (it's okay not to do this if an error
 145      *                      indication is returned)
 146      * \param bufstart      For calculating the correct offset parameter for
 147      *                      the \a output_value calls: *bufp - bufstart.
 148      * \param d             data to pass to each call to
 149      *                      output_value/output_reloc
 150      * \param output_value  function to call to convert values into their byte
 151      *                      representation
 152      * \param output_reloc  function to call to output relocation entries
 153      *                      for a single sym
 154      * \return Nonzero on error, 0 on success.
 155      * \note May result in non-reversible changes to the bytecode, but it's
 156      *       preferable if calling this function twice would result in the
 157      *       same output.
 158      */
 159     int (*tobytes) (yasm_bytecode *bc, unsigned char **bufp,
 160                     unsigned char *bufstart, void *d,
 161                     yasm_output_value_func output_value,
 162                     /*@null@*/ yasm_output_reloc_func output_reloc);
 163
 164     /** Special bytecode classifications.  Most bytecode types should use
 165      * #YASM_BC_SPECIAL_NONE.  Others cause special handling to kick in
 166      * in various parts of yasm.
 167      */
 168     enum yasm_bytecode_special_type {
 169         YASM_BC_SPECIAL_NONE = 0,
 170
 171         /** Bytecode reserves space instead of outputting data. */
 172         YASM_BC_SPECIAL_RESERVE,
 173
 174         /** Adjusts offset instead of calculating len. */
 175         YASM_BC_SPECIAL_OFFSET,
 176
 177         /** Instruction bytecode. */
 178         YASM_BC_SPECIAL_INSN
 179     } special;
 180 } yasm_bytecode_callback;
 181
 182 /** A bytecode. */
 183 struct yasm_bytecode {
 184     /** Bytecodes are stored as a singly linked list, with tail insertion.
 185      * \see section.h (#yasm_section).
 186      */
 187     /*@reldef@*/ STAILQ_ENTRY(yasm_bytecode) link;
 188
 189     /** The bytecode callback structure for this bytecode.  May be NULL
 190      * during partial initialization.
 191      */
 192     /*@null@*/ const yasm_bytecode_callback *callback;
 193
 194     /** Pointer to section containing bytecode; NULL if not part of a
 195      * section.
 196      */
 197     /*@dependent@*/ /*@null@*/ yasm_section *section;
 198
 199     /** Number of times bytecode is repeated.
 200      * NULL=1 (to save space in the common case).
 201      */
 202     /*@only@*/ /*@null@*/ yasm_expr *multiple;
 203
 204     /** Total length of entire bytecode (not including multiple copies). */
 205     unsigned long len;
 206
 207     /** Number of copies, integer version. */
 208     long mult_int;
 209
 210     /** Line number where bytecode was defined. */
 211     unsigned long line;
 212
 213     /** Offset of bytecode from beginning of its section.
 214      * 0-based, ~0UL (e.g. all 1 bits) if unknown.
 215      */
 216     unsigned long offset;
 217
 218     /** Unique integer index of bytecode.  Used during optimization. */
 219     unsigned long bc_index;
 220
 221     /** NULL-terminated array of labels that point to this bytecode (as the
 222      * bytecode previous to the label).  NULL if no labels point here.
 223      */
 224     /*@null@*/ yasm_symrec **symrecs;
 225
 226     /** Implementation-specific data (type identified by callback). */
 227     void *contents;
 228 };
 229
 230 /** Create a bytecode of any specified type.
 231  * \param callback      bytecode callback functions, if NULL, creates empty
 232  *                      bytecode (may not be resolved or output)
 233  * \param contents      type-specific data
 234  * \param line          virtual line (from yasm_linemap)
 235  * \return Newly allocated bytecode of the specified type.
 236  */
 237 YASM_LIB_DECL
 238 /*@only@*/ yasm_bytecode *yasm_bc_create_common
 239     (/*@null@*/ const yasm_bytecode_callback *callback,
 240      /*@only@*/ /*@null@*/ void *contents, unsigned long line);
 241
 242 /** Transform a bytecode of any type into a different type.
 243  * \param bc            bytecode to transform
 244  * \param callback      new bytecode callback function
 245  * \param contents      new type-specific data
 246  */
 247 YASM_LIB_DECL
 248 void yasm_bc_transform(yasm_bytecode *bc,
 249                        const yasm_bytecode_callback *callback,
 250                        void *contents);
 251
 252 /** Common bytecode callback finalize function, for where no finalization
 253  * is ever required for this type of bytecode.
 254  */
 255 YASM_LIB_DECL
 256 void yasm_bc_finalize_common(yasm_bytecode *bc, yasm_bytecode *prev_bc);
 257
 258 /** Common bytecode callback calc_len function, for where the bytecode has
 259  * no calculatable length.  Causes an internal error if called.
 260  */
 261 YASM_LIB_DECL
 262 int yasm_bc_calc_len_common(yasm_bytecode *bc, yasm_bc_add_span_func add_span,
 263                             void *add_span_data);
 264
 265 /** Common bytecode callback expand function, for where the bytecode is
 266  * always short (calc_len never calls add_span).  Causes an internal
 267  * error if called.
 268  */
 269 YASM_LIB_DECL
 270 int yasm_bc_expand_common
 271     (yasm_bytecode *bc, int span, long old_val, long new_val,
 272      /*@out@*/ long *neg_thres, /*@out@*/ long *pos_thres);
 273
 274 /** Common bytecode callback tobytes function, for where the bytecode
 275  * cannot be converted to bytes.  Causes an internal error if called.
 276  */
 277 YASM_LIB_DECL
 278 int yasm_bc_tobytes_common
 279     (yasm_bytecode *bc, unsigned char **bufp, unsigned char *bufstart, void *d,
 280      yasm_output_value_func output_value,
 281      /*@null@*/ yasm_output_reloc_func output_reloc);
 282
 283 /** Get the next bytecode in a linked list of bytecodes.
 284  * \param bc    bytecode
 285  * \return Next bytecode.
 286  */
 287 #define yasm_bc__next(bc)               STAILQ_NEXT(bc, link)
 288
 289 /** Set multiple field of a bytecode.
 290  * A bytecode can be repeated a number of times when output.  This function
 291  * sets that multiple.
 292  * \param bc    bytecode
 293  * \param e     multiple (kept, do not free)
 294  */
 295 YASM_LIB_DECL
 296 void yasm_bc_set_multiple(yasm_bytecode *bc, /*@keep@*/ yasm_expr *e);
 297
 298 /** Create a bytecode containing data value(s).
 299  * \param datahead      list of data values (kept, do not free)
 300  * \param size          storage size (in bytes) for each data value
 301  * \param append_zero   append a single zero byte after each data value
 302  *                      (if non-zero)
 303  * \param arch          architecture (optional); if provided, data items
 304  *                      are directly simplified to bytes if possible
 305  * \param line          virtual line (from yasm_linemap)
 306  * \return Newly allocated bytecode.
 307  */
 308 YASM_LIB_DECL
 309 /*@only@*/ yasm_bytecode *yasm_bc_create_data
 310     (yasm_datavalhead *datahead, unsigned int size, int append_zero,
 311      /*@null@*/ yasm_arch *arch, unsigned long line);
 312
 313 /** Create a bytecode containing LEB128-encoded data value(s).
 314  * \param datahead      list of data values (kept, do not free)
 315  * \param sign          signedness (1=signed, 0=unsigned) of each data value
 316  * \param line          virtual line (from yasm_linemap)
 317  * \return Newly allocated bytecode.
 318  */
 319 YASM_LIB_DECL
 320 /*@only@*/ yasm_bytecode *yasm_bc_create_leb128
 321     (yasm_datavalhead *datahead, int sign, unsigned long line);
 322
 323 /** Create a bytecode reserving space.
 324  * \param numitems      number of reserve "items" (kept, do not free)
 325  * \param itemsize      reserved size (in bytes) for each item
 326  * \param line          virtual line (from yasm_linemap)
 327  * \return Newly allocated bytecode.
 328  */
 329 YASM_LIB_DECL
 330 /*@only@*/ yasm_bytecode *yasm_bc_create_reserve
 331     (/*@only@*/ yasm_expr *numitems, unsigned int itemsize,
 332      unsigned long line);
 333
 334 /** Get the number of items and itemsize for a reserve bytecode.  If bc
 335  * is not a reserve bytecode, returns NULL.
 336  * \param bc            bytecode
 337  * \param itemsize      reserved size (in bytes) for each item (returned)
 338  * \return NULL if bc is not a reserve bytecode, otherwise an expression
 339  *         for the number of items to reserve.
 340  */
 341 YASM_LIB_DECL
 342 /*@null@*/ const yasm_expr *yasm_bc_reserve_numitems
 343     (yasm_bytecode *bc, /*@out@*/ unsigned int *itemsize);
 344
 345 /** Create a bytecode that includes a binary file verbatim.
 346  * \param filename      path to binary file (kept, do not free)
 347  * \param start         starting location in file (in bytes) to read data from
 348  *                      (kept, do not free); may be NULL to indicate 0
 349  * \param maxlen        maximum number of bytes to read from the file (kept, do
 350  *                      do not free); may be NULL to indicate no maximum
 351  * \param linemap       line mapping repository
 352  * \param line          virtual line (from yasm_linemap) for the bytecode
 353  * \return Newly allocated bytecode.
 354  */
 355 YASM_LIB_DECL
 356 /*@only@*/ yasm_bytecode *yasm_bc_create_incbin
 357     (/*@only@*/ char *filename, /*@only@*/ /*@null@*/ yasm_expr *start,
 358      /*@only@*/ /*@null@*/ yasm_expr *maxlen, yasm_linemap *linemap,
 359      unsigned long line);
 360
 361 /** Create a bytecode that aligns the following bytecode to a boundary.
 362  * \param boundary      byte alignment (must be a power of two)
 363  * \param fill          fill data (if NULL, code_fill or 0 is used)
 364  * \param maxskip       maximum number of bytes to skip
 365  * \param code_fill     code fill data (if NULL, 0 is used)
 366  * \param line          virtual line (from yasm_linemap)
 367  * \return Newly allocated bytecode.
 368  * \note The precedence on generated fill is as follows:
 369  *       - from fill parameter (if not NULL)
 370  *       - from code_fill parameter (if not NULL)
 371  *       - 0
 372  */
 373 YASM_LIB_DECL
 374 /*@only@*/ yasm_bytecode *yasm_bc_create_align
 375     (/*@keep@*/ yasm_expr *boundary, /*@keep@*/ /*@null@*/ yasm_expr *fill,
 376      /*@keep@*/ /*@null@*/ yasm_expr *maxskip,
 377      /*@null@*/ const unsigned char **code_fill, unsigned long line);
 378
 379 /** Create a bytecode that puts the following bytecode at a fixed section
 380  * offset.
 381  * \param start         section offset of following bytecode
 382  * \param fill          fill value
 383  * \param line          virtual line (from yasm_linemap)
 384  * \return Newly allocated bytecode.
 385  */
 386 YASM_LIB_DECL
 387 /*@only@*/ yasm_bytecode *yasm_bc_create_org
 388     (unsigned long start, unsigned long fill, unsigned long line);
 389
 390 /** Get the section that contains a particular bytecode.
 391  * \param bc    bytecode
 392  * \return Section containing bc (can be NULL if bytecode is not part of a
 393  *         section).
 394  */
 395 YASM_LIB_DECL
 396 /*@dependent@*/ /*@null@*/ yasm_section *yasm_bc_get_section
 397     (yasm_bytecode *bc);
 398
 399 /** Add to the list of symrecs that reference a bytecode.  For symrec use
 400  * only.
 401  * \param bc    bytecode
 402  * \param sym   symbol
 403  */
 404 YASM_LIB_DECL
 405 void yasm_bc__add_symrec(yasm_bytecode *bc, /*@dependent@*/ yasm_symrec *sym);
 406
 407 /** Delete (free allocated memory for) a bytecode.
 408  * \param bc    bytecode (only pointer to it); may be NULL
 409  */
 410 YASM_LIB_DECL
 411 void yasm_bc_destroy(/*@only@*/ /*@null@*/ yasm_bytecode *bc);
 412
 413 /** Print a bytecode.  For debugging purposes.
 414  * \param f             file
 415  * \param indent_level  indentation level
 416  * \param bc            bytecode
 417  */
 418 YASM_LIB_DECL
 419 void yasm_bc_print(const yasm_bytecode *bc, FILE *f, int indent_level);
 420
 421 /** Finalize a bytecode after parsing.
 422  * \param bc            bytecode
 423  * \param prev_bc       bytecode directly preceding bc in a list of bytecodes
 424  */
 425 YASM_LIB_DECL
 426 void yasm_bc_finalize(yasm_bytecode *bc, yasm_bytecode *prev_bc);
 427
 428 /** Determine the distance between the starting offsets of two bytecodes.
 429  * \param precbc1       preceding bytecode to the first bytecode
 430  * \param precbc2       preceding bytecode to the second bytecode
 431  * \return Distance in bytes between the two bytecodes (bc2-bc1), or NULL if
 432  *         the distance was indeterminate.
 433  * \warning Only valid /after/ optimization.
 434  */
 435 YASM_LIB_DECL
 436 /*@null@*/ /*@only@*/ yasm_intnum *yasm_calc_bc_dist
 437     (yasm_bytecode *precbc1, yasm_bytecode *precbc2);
 438
 439 /** Get the offset of the next bytecode (the next bytecode doesn't have to
 440  * actually exist).
 441  * \param precbc        preceding bytecode
 442  * \return Offset of the next bytecode in bytes.
 443  * \warning Only valid /after/ optimization.
 444  */
 445 YASM_LIB_DECL
 446 unsigned long yasm_bc_next_offset(yasm_bytecode *precbc);
 447
 448 /** Return elemens size of a data bytecode.
 449  * Returns the size of each elements of a data bytecode, for proper dereference
 450  * of symbols attached to it.
 451  * \param bc            bytecode
 452  * \return 0 if element size is unknown
 453  */
 454 YASM_LIB_DECL
 455 int yasm_bc_elem_size(yasm_bytecode *bc);
 456
 457 /** Resolve EQUs in a bytecode and calculate its minimum size.
 458  * Generates dependent bytecode spans for cases where, if the length spanned
 459  * increases, it could cause the bytecode size to increase.
 460  * Any bytecode multiple is NOT included in the length or spans generation;
 461  * this must be handled at a higher level.
 462  * \param bc            bytecode
 463  * \param add_span      function to call to add a span
 464  * \param add_span_data extra data to be passed to add_span function
 465  * \return 0 if no error occurred, nonzero if there was an error recognized
 466  *         (and output) during execution.
 467  * \note May store to bytecode updated expressions and the short length.
 468  */
 469 YASM_LIB_DECL
 470 int yasm_bc_calc_len(yasm_bytecode *bc, yasm_bc_add_span_func add_span,
 471                      void *add_span_data);
 472
 473 /** Recalculate a bytecode's length based on an expanded span length.
 474  * \param bc            bytecode
 475  * \param span          span ID (as given to yasm_bc_add_span_func in
 476  *                      yasm_bc_calc_len)
 477  * \param old_val       previous span value
 478  * \param new_val       new span value
 479  * \param neg_thres     negative threshold for long/short decision (returned)
 480  * \param pos_thres     positive threshold for long/short decision (returned)
 481  * \return 0 if bc no longer dependent on this span's length, negative if
 482  *         there was an error recognized (and output) during execution, and
 483  *         positive if bc size may increase for this span further based on the
 484  *         new negative and positive thresholds returned.
 485  * \note May store to bytecode updated expressions and the updated length.
 486  */
 487 YASM_LIB_DECL
 488 int yasm_bc_expand(yasm_bytecode *bc, int span, long old_val, long new_val,
 489                    /*@out@*/ long *neg_thres, /*@out@*/ long *pos_thres);
 490
 491 /** Convert a bytecode into its byte representation.
 492  * \param bc            bytecode
 493  * \param buf           byte representation destination buffer
 494  * \param bufsize       size of buf (in bytes) prior to call; size of the
 495  *                      generated data after call
 496  * \param gap           if nonzero, indicates the data does not really need to
 497  *                      exist in the object file; if nonzero, contents of buf
 498  *                      are undefined [output]
 499  * \param d             data to pass to each call to output_value/output_reloc
 500  * \param output_value  function to call to convert values into their byte
 501  *                      representation
 502  * \param output_reloc  function to call to output relocation entries
 503  *                      for a single sym
 504  * \return Newly allocated buffer that should be used instead of buf for
 505  *         reading the byte representation, or NULL if buf was big enough to
 506  *         hold the entire byte representation.
 507  * \note Calling twice on the same bytecode may \em not produce the same
 508  *       results on the second call, as calling this function may result in
 509  *       non-reversible changes to the bytecode.
 510  */
 511 YASM_LIB_DECL
 512 /*@null@*/ /*@only@*/ unsigned char *yasm_bc_tobytes
 513     (yasm_bytecode *bc, unsigned char *buf, unsigned long *bufsize,
 514      /*@out@*/ int *gap, void *d, yasm_output_value_func output_value,
 515      /*@null@*/ yasm_output_reloc_func output_reloc)
 516     /*@sets *buf@*/;
 517
 518 /** Get the bytecode multiple value as an integer.
 519  * \param bc            bytecode
 520  * \param multiple      multiple value (output)
 521  * \param calc_bc_dist  nonzero if distances between bytecodes should be
 522  *                      calculated, 0 if error should be returned in this case
 523  * \return 1 on error (set with yasm_error_set), 0 on success.
 524  */
 525 YASM_LIB_DECL
 526 int yasm_bc_get_multiple(yasm_bytecode *bc, /*@out@*/ long *multiple,
 527                          int calc_bc_dist);
 528
 529 /** Get the bytecode multiple value as an expression.
 530  * \param bc            bytecode
 531  * \return Bytecode multiple, NULL if =1.
 532  */
 533 YASM_LIB_DECL
 534 const yasm_expr *yasm_bc_get_multiple_expr(const yasm_bytecode *bc);
 535
 536 /** Get a #yasm_insn structure from an instruction bytecode (if possible).
 537  * \param bc            bytecode
 538  * \return Instruction details if bytecode is an instruction bytecode,
 539  *         otherwise NULL.
 540  */
 541 YASM_LIB_DECL
 542 /*@dependent@*/ /*@null@*/ yasm_insn *yasm_bc_get_insn(yasm_bytecode *bc);
 543
 544 /** Create a new data value from an expression.
 545  * \param expn  expression
 546  * \return Newly allocated data value.
 547  */
 548 YASM_LIB_DECL
 549 yasm_dataval *yasm_dv_create_expr(/*@keep@*/ yasm_expr *expn);
 550
 551 /** Create a new data value from a string.
 552  * \param contents      string (may contain NULs)
 553  * \param len           length of string
 554  * \return Newly allocated data value.
 555  */
 556 yasm_dataval *yasm_dv_create_string(/*@keep@*/ char *contents, size_t len);
 557
 558 /** Create a new data value from raw bytes data.
 559  * \param contents      raw data (may contain NULs)
 560  * \param len           length
 561  * \return Newly allocated data value.
 562  */
 563 YASM_LIB_DECL
 564 yasm_dataval *yasm_dv_create_raw(/*@keep@*/ unsigned char *contents,
 565                                  unsigned long len);
 566
 567 /** Create a new uninitialized data value.
 568  * \return Newly allocated data value.
 569  */
 570 yasm_dataval *yasm_dv_create_reserve(void);
 571
 572 #ifndef YASM_DOXYGEN
 573 #define yasm_dv_create_string(s, l) yasm_dv_create_raw((unsigned char *)(s), \
 574                                                        (unsigned long)(l))
 575 #endif
 576
 577 /** Get the underlying value of a data value.
 578  * \param dv    data value
 579  * \return Value, or null if non-value (e.g. string or raw).
 580  */
 581 yasm_value *yasm_dv_get_value(yasm_dataval *dv);
 582
 583 /** Set multiple field of a data value.
 584  * A data value can be repeated a number of times when output.  This function
 585  * sets that multiple.
 586  * \param dv    data value
 587  * \param e     multiple (kept, do not free)
 588  */
 589 void yasm_dv_set_multiple(yasm_dataval *dv, /*@keep@*/ yasm_expr *e);
 590
 591 /** Get the data value multiple value as an unsigned long integer.
 592  * \param dv            data value
 593  * \param multiple      multiple value (output)
 594  * \return 1 on error (set with yasm_error_set), 0 on success.
 595  */
 596 int yasm_dv_get_multiple(yasm_dataval *dv, /*@out@*/ unsigned long *multiple);
 597
 598 /** Initialize a list of data values.
 599  * \param headp list of data values
 600  */
 601 void yasm_dvs_initialize(yasm_datavalhead *headp);
 602 #ifndef YASM_DOXYGEN
 603 #define yasm_dvs_initialize(headp)      STAILQ_INIT(headp)
 604 #endif
 605
 606 /** Delete (free allocated memory for) a list of data values.
 607  * \param headp list of data values
 608  */
 609 YASM_LIB_DECL
 610 void yasm_dvs_delete(yasm_datavalhead *headp);
 611
 612 /** Add data value to the end of a list of data values.
 613  * \note Does not make a copy of the data value; so don't pass this function
 614  *       static or local variables, and discard the dv pointer after calling
 615  *       this function.
 616  * \param headp         data value list
 617  * \param dv            data value (may be NULL)
 618  * \return If data value was actually appended (it wasn't NULL), the data
 619  *         value; otherwise NULL.
 620  */
 621 YASM_LIB_DECL
 622 /*@null@*/ yasm_dataval *yasm_dvs_append
 623     (yasm_datavalhead *headp, /*@returned@*/ /*@null@*/ yasm_dataval *dv);
 624
 625 /** Print a data value list.  For debugging purposes.
 626  * \param f             file
 627  * \param indent_level  indentation level
 628  * \param headp         data value list
 629  */
 630 YASM_LIB_DECL
 631 void yasm_dvs_print(const yasm_datavalhead *headp, FILE *f, int indent_level);
 632
 633 #endif