xref: /illumos-gate/usr/src/lib/libdwarf/common/dwarf_line.h (revision 4d9fdb46b215739778ebc12079842c9905586999)
1 /*
2   Copyright (C) 2000, 2004, 2006 Silicon Graphics, Inc.  All Rights Reserved.
3   Portions Copyright (C) 2009-2015 David Anderson. All Rights Reserved.
4   Portions Copyright (C) 2010-2012 SN Systems Ltd. All Rights Reserved.
5 
6   This program is free software; you can redistribute it and/or modify it
7   under the terms of version 2.1 of the GNU Lesser General Public License
8   as published by the Free Software Foundation.
9 
10   This program is distributed in the hope that it would be useful, but
11   WITHOUT ANY WARRANTY; without even the implied warranty of
12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13 
14   Further, this software is distributed without any warranty that it is
15   free of the rightful claim of any third person regarding infringement
16   or the like.  Any license provided herein, whether implied or
17   otherwise, applies only to this software file.  Patent licenses, if
18   any, provided herein do not apply to combinations of this program with
19   other software, or any other product whatsoever.
20 
21   You should have received a copy of the GNU Lesser General Public
22   License along with this program; if not, write the Free Software
23   Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston MA 02110-1301,
24   USA.
25 
26 */
27 
28 
29 
30 #define DW_EXTENDED_OPCODE   0
31 
32 /*
33     This is used as the starting value for an algorithm
34     to get the minimum difference between 2 values.
35     UINT_MAX is used as our approximation to infinity.
36 */
37 #define MAX_LINE_DIFF       UINT_MAX
38 
39 /* This is for a sanity check on line
40    table extended opcodes.
41    It is entirely arbitrary, and 100 is surely too small if
42    someone was inserting strings in the opcode. */
43 #define DW_LNE_LEN_MAX   100
44 
45 
46 /*
47     This structure is used to build a list of all the
48     files that are used in the current compilation unit.
49     All of the fields execpt fi_next have meanings that
50     are obvious from section 6.2.4 of the Libdwarf Doc.
51     Because of DW_LNE_define_file we
52     make this a list, not an array.
53 */
54 struct Dwarf_File_Entry_s {
55     struct Dwarf_File_Entry_s *fi_next;
56 
57     /* Points to string naming the file. */
58     Dwarf_Small *fi_file_name;
59 
60     /*  Index into the list of directories of the directory in which
61         this file exits. */
62     Dwarf_Unsigned fi_dir_index;
63 
64     /* Time of last modification of the file. */
65     Dwarf_Unsigned fi_time_last_mod;
66 
67     /* Length in bytes of the file. */
68     Dwarf_Unsigned fi_file_length;
69 
70     Dwarf_Form_Data16   fi_md5_value;
71     char           fi_dir_index_present;
72     char           fi_time_last_mod_present;
73     char           fi_file_length_present;
74     char           fi_md5_present;
75 };
76 
77 /*  Part of two-level line tables support. */
78 struct Dwarf_Subprog_Entry_s {
79     Dwarf_Small *ds_subprog_name;
80     Dwarf_Unsigned ds_decl_file;
81     Dwarf_Unsigned ds_decl_line;
82 };
83 
84 typedef struct Dwarf_Subprog_Entry_s *Dwarf_Subprog_Entry;
85 
86 
87 struct Dwarf_Unsigned_Pair_s {
88     Dwarf_Unsigned  up_first;
89     Dwarf_Unsigned  up_second;
90 };
91 
92 /*
93     This structure provides the context in which the fields of
94     a Dwarf_Line structure are interpreted.  They come from the
95     statement program prologue.  **Updated by dwarf_srclines in
96     dwarf_line.c.
97 
98     lc_magic will be DW_CONTEXT_MAGIC unless there is a serious
99     programming error somewhere.
100     It's set zero when a Line_Context is deallocated.
101     Any other value indicates there is bug somewhere.
102 */
103 #define DW_CONTEXT_MAGIC 0xd00d1111
104 struct Dwarf_Line_Context_s {
105     unsigned    lc_magic;
106 
107     /*  lc_new_style_access is non-zero if this was allocated
108         via a dwarf_srclines_b() call or equivalent.
109         Otherwise this is 0.  */
110     unsigned char lc_new_style_access;
111 
112     Dwarf_Unsigned lc_unit_length; /* all versions */
113 
114     /* The section offset (in .debug_line
115         or .debug_line.dwo of the line table */
116     Dwarf_Unsigned lc_section_offset;
117 
118     /*  2 for DWARF2, 3 for DWARF3, 4 for DWARF4, 5 for DWARF5.
119         0xf006 for experimental two-level line tables. */
120     Dwarf_Half lc_version_number; /* all versions */
121 
122     /* Total length of the line data for this CU */
123     Dwarf_Unsigned lc_total_length; /* all versions */
124 
125     /* Length of the initial length field itself. */
126     Dwarf_Half lc_length_field_length; /* all versions */
127 
128     /* address size and segment sizefields new in DWARF5 header.  */
129     Dwarf_Small lc_address_size; /* DWARF5 */
130     Dwarf_Small lc_segment_selector_size; /* DWARF5 */
131 
132     Dwarf_Unsigned lc_header_length; /* all versions */
133 
134     Dwarf_Unsigned lc_prologue_length;
135     Dwarf_Unsigned lc_actuals_table_offset;
136     Dwarf_Unsigned lc_logicals_table_offset;
137     Dwarf_Small lc_minimum_instruction_length;  /* all versions */
138     Dwarf_Ubyte lc_maximum_ops_per_instruction; /*DWARF5*/
139 
140     /*  Start and end of this CU line area. pf_line_ptr_start +
141         pf_total_length + pf_length_field_length == pf_line_ptr_end.
142         Meaning lc_line_ptr_start is before the length info. */
143     Dwarf_Small *lc_line_ptr_start;
144     Dwarf_Small *lc_line_ptr_end;
145     /*  Start of the lines themselves. */
146     Dwarf_Small *lc_line_ptr_lines;
147 
148     /* Used to check that decoding of the line prologue is done right. */
149     Dwarf_Small *lc_line_prologue_start;
150 
151     Dwarf_Small lc_default_is_stmt; /* all versions */
152     Dwarf_Sbyte lc_line_base;  /* all versions */
153     Dwarf_Small lc_line_range;  /* all versions */
154 
155     /* Highest std opcode (+1).  */
156     Dwarf_Small lc_opcode_base; /* all versions */
157     /*  pf_opcode_base -1 entries (each a count, normally the value of
158         each entry is 0 or 1). */
159     Dwarf_Small *lc_opcode_length_table; /* all versions */
160 
161     /*  The number to treat as standard ops. This is a special
162         accomodation of gcc using the new standard opcodes but not
163         updating the version number. It's legal dwarf2, but much better
164         for the user to understand as dwarf3 when 'it looks ok'. */
165     Dwarf_Small lc_std_op_count;
166 
167     /* ======== includes =========*/
168     /*  Points to the portion of .debug_line section that
169         contains a list of strings naming the included
170         directories.  Do not free().
171         No free even DWARF5?
172         An array of pointers to strings.  */
173     /*  DWARF 2,3,4: does not name the current dir of the compilation.
174         DWARF5: Initial entry is the dir of the compilation. */
175     Dwarf_Small **lc_include_directories;
176     /*  Count of the number of included directories. */
177     Dwarf_Unsigned lc_include_directories_count;
178 
179     /* count of uleb pairs */
180     Dwarf_Unsigned lc_directory_entry_format_count; /* DWARF5 */
181 
182     Dwarf_Unsigned lc_directory_entry_values_count; /* DWARF5 */
183     /*  This must be freed,malloc space, an array of the
184         values of each entry. */
185     struct Dwarf_Unsigned_Pair_s * lc_directory_format_values; /* DWARF5 */
186 
187     /* ======== end includes =========*/
188 
189     /* ======== file names =========*/
190 
191     Dwarf_Unsigned lc_file_name_format_count; /* DWARF5 */
192     Dwarf_Unsigned * lc_file_name_format; /* DWARF5 */
193     Dwarf_Unsigned lc_file_entry_values_count; /* DWARF5 */
194     /*  This must be freed,malloc space, an array of the
195         values of each entry. */
196     struct Dwarf_Unsigned_Pair_s * lc_file_format_values; /* DWARF5 */
197 
198     /*  Points to a singly-linked list of entries providing info
199         about source files
200         for the current set of Dwarf_Line structures.
201         The initial  entry on the list is 'file 1' per DWARF2,3,4 rules.
202         And so on.  lc_last_entry points at the last entry
203         in the list (so we can easily expand the list).
204         It's a list (not a table) since we may encounter
205         DW_LNE_define_file entries.
206         For Dwarf5 the initial entry is 'file 0'
207         and must match the CU-DIE DW_AT_name string. */
208     Dwarf_File_Entry lc_file_entries;
209     Dwarf_File_Entry lc_last_entry;
210     /*  Count of number of source files for this set of Dwarf_Line
211         structures. */
212     Dwarf_Unsigned lc_file_entry_count; /* all versions */
213     /*  Values Easing the process of indexing through lc_file_entries. */
214     Dwarf_Unsigned lc_file_entry_baseindex;
215     Dwarf_Unsigned lc_file_entry_endindex;
216     /* ======== end file names =========*/
217 
218 
219     /*  Points to an array of subprogram entries.
220         With Two level line tables this may be non-zero.
221         An array of Dwarf_Subprogram_Entry_s structs. */
222     Dwarf_Subprog_Entry lc_subprogs;
223 
224     /*  Count of the number of subprogram entries
225         With Two level line tables this may be non-zero. */
226     Dwarf_Unsigned lc_subprogs_count;
227 
228     /*  Count of the number of lines for this cu. */
229     Dwarf_Unsigned lc_line_count;
230 
231     /*  Points to name of compilation directory.
232         That string is in a .debug section  (DWARF 2,3,4)
233         so do not free this. For DWARF5 must be the same
234         as lc_include_directories[0] */
235     Dwarf_Small *lc_compilation_directory;
236 
237     Dwarf_Debug lc_dbg;
238 
239     /*  zero table count is skeleton, or just missing names.
240         1 is standard table.
241         2 means two-level table (experimantal)
242         Other is a bug somewhere.  */
243     Dwarf_Small lc_table_count;
244     Dwarf_Bool lc_is_single_table;
245 
246     /* For standard line tables  the logicals are
247         the only tables and linecount_actuals is 0. */
248     Dwarf_Line   *lc_linebuf_logicals;
249     Dwarf_Unsigned lc_linecount_logicals;
250 
251     /* Non-zero only if two-level table with actuals */
252     Dwarf_Line   *lc_linebuf_actuals;
253     Dwarf_Unsigned lc_linecount_actuals;
254 };
255 
256 
257 
258 /*  The line table set of registers.
259     The state machine state variables.
260     Using names from the DWARF documentation
261     but preceded by lr_.  */
262 struct Dwarf_Line_Registers_s {
263     Dwarf_Addr lr_address;        /* DWARF2 */
264     Dwarf_Unsigned lr_file ;          /* DWARF2 */
265     Dwarf_Unsigned lr_line ;          /* DWARF2 */
266     Dwarf_Unsigned lr_column ;        /* DWARF2 */
267     Dwarf_Bool lr_is_stmt;        /* DWARF2 */
268     Dwarf_Bool lr_basic_block;    /* DWARF2 */
269     Dwarf_Bool lr_end_sequence;   /* DWARF2 */
270     Dwarf_Bool lr_prologue_end;   /* DWARF3 */
271     Dwarf_Bool lr_epilogue_begin; /* DWARF3 */
272     Dwarf_Small lr_isa;           /* DWARF3 */
273     Dwarf_Unsigned lr_op_index;      /* DWARF4, operation within VLIW instruction. */
274     Dwarf_Unsigned lr_discriminator; /* DWARF4 */
275     Dwarf_Unsigned lr_call_context;       /* EXPERIMENTAL */
276     Dwarf_Unsigned lr_subprogram;     /* EXPERIMENTAL */
277 };
278 typedef struct Dwarf_Line_Registers_s *Dwarf_Line_Registers;
279 void _dwarf_set_line_table_regs_default_values(
280     Dwarf_Line_Registers regs,
281     unsigned lineversion,
282     Dwarf_Bool is_stmt);
283 
284 
285 
286 /*
287     This structure defines a row of the line table.
288     All of the fields except li_offset have the exact
289     same meaning that is defined in Section 6.2.2
290     of the Libdwarf Document.
291 
292     li_offset is used by _dwarf_addr_finder() which is called
293     by rqs(1), an sgi utility for 'moving' shared libraries
294     as if the static linker (ld) had linked the shared library
295     at the newly-specified address.  Most libdwarf-using
296     apps will ignore li_offset and _dwarf_addr_finder().
297 
298 */
299 struct Dwarf_Line_s {
300     Dwarf_Addr li_address;  /* pc value of machine instr */
301     union addr_or_line_s {
302         struct li_inner_s {
303             /* New as of DWARF4 */
304             Dwarf_Unsigned li_discriminator;
305 
306             /*  int identifying src file
307                 li_file is a number 1-N, indexing into a conceptual
308                 source file table as described in dwarf2/3 spec line
309                 table doc. (see Dwarf_File_Entry lc_file_entries; and
310                 Dwarf_Unsigned lc_file_entry_count;) */
311             Dwarf_Unsigned li_file;
312 
313             /*  In single-level table is line number in source file. 1-N
314                 In logicals table is not used.
315                 In actuals table is index into logicals table.  1-N*/
316             Dwarf_Unsigned li_line;
317 
318             Dwarf_Half li_column; /* source file column number  1-N */
319             Dwarf_Small li_isa;   /* New as of DWARF4. */
320 
321             /*  Two-level line tables.
322                 Is index from logicals table
323                 into logicals table. 1-N */
324             Dwarf_Unsigned li_call_context;
325 
326             /*  Two-level line tables.
327                 is index into subprograms table. 1-N */
328             Dwarf_Unsigned li_subprogram;
329 
330             /* To save space, use bit flags. */
331             /* indicate start of stmt */
332             unsigned li_is_stmt:1;
333 
334             /* indicate start basic block */
335             unsigned li_basic_block:1;
336 
337             /* first post sequence instr */
338             unsigned li_end_sequence:1;
339 
340             unsigned li_prologue_end:1;
341             unsigned li_epilogue_begin:1;
342 
343             /* Mark a line record as being DW_LNS_set_address. */
344             unsigned li_is_addr_set:1;
345         } li_l_data;
346 #ifdef __sgi /* SGI IRIX ONLY */
347         Dwarf_Off li_offset;  /* for SGI IRIX rqs only*/
348 #endif /* __sgi */
349     } li_addr_line;
350     Dwarf_Line_Context li_context; /* assoc Dwarf_Line_Context_s */
351 
352     /*  Set only on the actuals table of a two-level line table.
353         Assists in the dealloc code.
354     */
355     Dwarf_Bool li_is_actuals_table;
356 };
357 
358 
359 int _dwarf_line_address_offsets(Dwarf_Debug dbg,
360     Dwarf_Die die,
361     Dwarf_Addr ** addrs,
362     Dwarf_Off ** offs,
363     Dwarf_Unsigned * returncount,
364     Dwarf_Error * err);
365 int _dwarf_internal_srclines(Dwarf_Die die,
366     Dwarf_Bool old_interface,
367     Dwarf_Unsigned * version,
368     Dwarf_Small     * table_count,
369     Dwarf_Line_Context *line_context,
370     Dwarf_Line ** linebuf,
371     Dwarf_Signed * count,
372     Dwarf_Line ** linebuf_actuals,
373     Dwarf_Signed * count_actuals,
374     Dwarf_Bool doaddrs,
375     Dwarf_Bool dolines,
376     Dwarf_Error * error);
377 
378 /*  The LOP, WHAT_IS_OPCODE stuff is here so it can
379     be reused in 3 places.  Seemed hard to keep
380     the 3 places the same without an inline func or
381     a macro.
382 
383     Handling the line section where the header and the
384     file being processed do not match (unusual, but
385     planned for in the  design of .debug_line)
386     is too tricky to recode this several times and keep
387     it right.
388 
389     As it is the code starting up line-reading is duplicated
390     and that is just wrong to do. FIXME!
391 */
392 #define LOP_EXTENDED 1
393 #define LOP_DISCARD  2
394 #define LOP_STANDARD 3
395 #define LOP_SPECIAL  4
396 
397 #define WHAT_IS_OPCODE(type,opcode,base,opcode_length,line_ptr,highest_std) \
398     if ((opcode) < (base)) {                             \
399         /*  we know we must treat as a standard op       \
400             or a special case. */                        \
401         if ((opcode) == DW_EXTENDED_OPCODE) {            \
402             type = LOP_EXTENDED;                         \
403         } else if ((highest_std+1) >= (base)) {        \
404             /*  == Standard case: compile of             \
405                 dwarf_line.c and object                  \
406                 have same standard op codes set.         \
407                 == Special case: compile of dwarf_line.c \
408                 has things in standard op codes list     \
409                 in dwarf.h header not                    \
410                 in the object: handle this as a standard \
411                 op code in switch below.                 \
412                 The header special ops overlap the       \
413                 object standard ops.                     \
414                 The new standard op codes will not       \
415                 appear in the object. */                 \
416             type = LOP_STANDARD;                         \
417         } else  {                                        \
418             /* These are standard opcodes in the object  \
419             ** that were not defined  in the header      \
420             ** at the time dwarf_line.c                  \
421             ** was compiled. Provides the ability of     \
422             ** out-of-date dwarf reader to read newer    \
423             ** line table data transparently.            \
424             */                                           \
425             type = LOP_DISCARD;                          \
426         }                                                \
427     } else {                                             \
428         /* Is  a special op code. */                     \
429         type =  LOP_SPECIAL;                             \
430     }
431 
432 /*  The following is from  the dwarf definition of 'ubyte'
433     and is specifically  mentioned in section  6.2.5.1, page 54
434     of the Rev 2.0.0 dwarf specification.
435 */
436 
437 #define MAX_LINE_OP_CODE  255
438 
439 /* Operand counts per standard operand.
440    The initial zero is for DW_LNS_copy.
441    This is an economical way to verify we understand the table
442    of standard-opcode-lengths in the line table prologue.  */
443 #define STANDARD_OPERAND_COUNT_DWARF2 9
444 #define STANDARD_OPERAND_COUNT_DWARF3 12
445 /* For two-level line tables, we have three additional standard opcodes. */
446 #define STANDARD_OPERAND_COUNT_TWO_LEVEL 15
447 
448 void _dwarf_print_header_issue(Dwarf_Debug dbg,
449     const char *specific_msg,
450     Dwarf_Small *data_start,
451     Dwarf_Signed value,
452     unsigned index,
453     unsigned tabv,
454     unsigned linetabv,
455     int *err_count_out);
456 int _dwarf_decode_line_string_form(Dwarf_Debug dbg,
457     Dwarf_Unsigned form,
458     Dwarf_Unsigned offset_size,
459     Dwarf_Small **line_ptr,
460     Dwarf_Small *line_ptr_end,
461     char **return_str,
462     Dwarf_Error * error);
463 int _dwarf_decode_line_udata_form(Dwarf_Debug dbg,
464     Dwarf_Unsigned form,
465     Dwarf_Small **line_ptr,
466     Dwarf_Unsigned *return_val,
467     Dwarf_Small *line_end_ptr,
468     Dwarf_Error * error);
469 
470 void _dwarf_update_chain_list( Dwarf_Chain chain_line,
471     Dwarf_Chain *head_chain, Dwarf_Chain *curr_chain);
472 void _dwarf_free_chain_entries(Dwarf_Debug dbg,Dwarf_Chain head,int count);
473 
474 int _dwarf_line_context_constructor(Dwarf_Debug dbg, void *m);
475 void _dwarf_line_context_destructor(void *m);
476 
477 void _dwarf_print_line_context_record(Dwarf_Debug dbg,
478     Dwarf_Line_Context line_context);
479 void _dwarf_context_src_files_destroy(Dwarf_Line_Context context);
480 int _dwarf_add_to_files_list(Dwarf_Line_Context context, Dwarf_File_Entry fe);
481