1 /** 2 * \file libyasm/linemap.h 3 * \brief YASM virtual line mapping 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 * 1. Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * 2. 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_LINEMAP_H 31 #define YASM_LINEMAP_H 32 33 #ifndef YASM_LIB_DECL 34 #define YASM_LIB_DECL 35 #endif 36 37 /** Create a new line mapping repository. 38 * \return New repository. 39 */ 40 YASM_LIB_DECL 41 yasm_linemap *yasm_linemap_create(void); 42 43 /** Clean up any memory allocated for a repository. 44 * \param linemap line mapping repository 45 */ 46 YASM_LIB_DECL 47 void yasm_linemap_destroy(yasm_linemap *linemap); 48 49 /** Get the current line position in a repository. 50 * \param linemap line mapping repository 51 * \return Current virtual line. 52 */ 53 YASM_LIB_DECL 54 unsigned long yasm_linemap_get_current(yasm_linemap *linemap); 55 56 /** Get bytecode and source line information, if any, for a virtual line. 57 * \param linemap line mapping repository 58 * \param line virtual line 59 * \param bcp pointer to return bytecode into 60 * \param sourcep pointer to return source code line pointer into 61 * \return Zero if source line information available for line, nonzero if not. 62 * \note If source line information is not available, bcp and sourcep targets 63 * are set to NULL. 64 */ 65 YASM_LIB_DECL 66 int yasm_linemap_get_source(yasm_linemap *linemap, unsigned long line, 67 /*@null@*/ yasm_bytecode **bcp, 68 const char **sourcep); 69 70 /** Add bytecode and source line information to the current virtual line. 71 * \attention Deletes any existing bytecode and source line information for 72 * the current virtual line. 73 * \param linemap line mapping repository 74 * \param bc bytecode (if any) 75 * \param source source code line 76 * \note The source code line pointer is NOT kept, it is strdup'ed. 77 */ 78 YASM_LIB_DECL 79 void yasm_linemap_add_source(yasm_linemap *linemap, 80 /*@null@*/ yasm_bytecode *bc, 81 const char *source); 82 83 /** Go to the next line (increments the current virtual line). 84 * \param linemap line mapping repository 85 * \return The current (new) virtual line. 86 */ 87 YASM_LIB_DECL 88 unsigned long yasm_linemap_goto_next(yasm_linemap *linemap); 89 90 /** Set a new file/line physical association starting point at the specified 91 * virtual line. line_inc indicates how much the "real" line is incremented 92 * by for each virtual line increment (0 is perfectly legal). 93 * \param linemap line mapping repository 94 * \param filename physical file name (if NULL, not changed) 95 * \param virtual_line virtual line number (if 0, linemap->current is used) 96 * \param file_line physical line number 97 * \param line_inc line increment 98 */ 99 YASM_LIB_DECL 100 void yasm_linemap_set(yasm_linemap *linemap, /*@null@*/ const char *filename, 101 unsigned long virtual_line, unsigned long file_line, 102 unsigned long line_inc); 103 104 /** Poke a single file/line association, restoring the original physical 105 * association starting point. Caution: increments the current virtual line 106 * twice. 107 * \param linemap line mapping repository 108 * \param filename physical file name (if NULL, not changed) 109 * \param file_line physical line number 110 * \return The virtual line number of the poked association. 111 */ 112 YASM_LIB_DECL 113 unsigned long yasm_linemap_poke(yasm_linemap *linemap, 114 /*@null@*/ const char *filename, 115 unsigned long file_line); 116 117 /** Look up the associated physical file and line for a virtual line. 118 * \param linemap line mapping repository 119 * \param line virtual line 120 * \param filename physical file name (output) 121 * \param file_line physical line number (output) 122 */ 123 YASM_LIB_DECL 124 void yasm_linemap_lookup(yasm_linemap *linemap, unsigned long line, 125 /*@out@*/ const char **filename, 126 /*@out@*/ unsigned long *file_line); 127 128 /** Traverses all filenames used in a linemap, calling a function on each 129 * filename. 130 * \param linemap line mapping repository 131 * \param d data pointer passed to func on each call 132 * \param func function 133 * \return Stops early (and returns func's return value) if func returns a 134 * nonzero value; otherwise 0. 135 */ 136 YASM_LIB_DECL 137 int yasm_linemap_traverse_filenames 138 (yasm_linemap *linemap, /*@null@*/ void *d, 139 int (*func) (const char *filename, void *d)); 140 141 #endif 142
