LineEntry.h revision 360660 
1//===-- LineEntry.h ---------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef liblldb_LineEntry_h_
10#define liblldb_LineEntry_h_
11
12#include "lldb/Core/AddressRange.h"
13#include "lldb/Utility/FileSpec.h"
14#include "lldb/lldb-private.h"
15
16namespace lldb_private {
17
18/// \class LineEntry LineEntry.h "lldb/Symbol/LineEntry.h"
19/// A line table entry class.
20struct LineEntry {
21  /// Default constructor.
22  ///
23  /// Initialize all member variables to invalid values.
24  LineEntry();
25
26  LineEntry(const lldb::SectionSP &section_sp, lldb::addr_t section_offset,
27            lldb::addr_t byte_size, const FileSpec &file, uint32_t _line,
28            uint16_t _column, bool _is_start_of_statement,
29            bool _is_start_of_basic_block, bool _is_prologue_end,
30            bool _is_epilogue_begin, bool _is_terminal_entry);
31
32  /// Clear the object's state.
33  ///
34  /// Clears all member variables to invalid values.
35  void Clear();
36
37  /// Dump a description of this object to a Stream.
38  ///
39  /// Dump a description of the contents of this object to the supplied stream
40  /// \a s.
41  ///
42  /// \param[in] s
43  ///     The stream to which to dump the object description.
44  ///
45  /// \param[in] comp_unit
46  ///     The compile unit object that contains the support file
47  ///     list so the line entry can dump the file name (since this
48  ///     object contains a file index into the support file list).
49  ///
50  /// \param[in] show_file
51  ///     If \b true, display the filename with the line entry which
52  ///     requires that the compile unit object \a comp_unit be a
53  ///     valid pointer.
54  ///
55  /// \param[in] style
56  ///     The display style for the section offset address.
57  ///
58  /// \return
59  ///     Returns \b true if the address was able to be displayed
60  ///     using \a style. File and load addresses may be unresolved
61  ///     and it may not be possible to display a valid address value.
62  ///     Returns \b false if the address was not able to be properly
63  ///     dumped.
64  ///
65  /// \see Address::DumpStyle
66  bool Dump(Stream *s, Target *target, bool show_file, Address::DumpStyle style,
67            Address::DumpStyle fallback_style, bool show_range) const;
68
69  bool GetDescription(Stream *s, lldb::DescriptionLevel level, CompileUnit *cu,
70                      Target *target, bool show_address_only) const;
71
72  /// Dumps information specific to a process that stops at this line entry to
73  /// the supplied stream \a s.
74  ///
75  /// \param[in] s
76  ///     The stream to which to dump the object description.
77  ///
78  /// \param[in] comp_unit
79  ///     The compile unit object that contains the support file
80  ///     list so the line entry can dump the file name (since this
81  ///     object contains a file index into the support file list).
82  ///
83  /// \return
84  ///     Returns \b true if the file and line were properly dumped,
85  ///     \b false otherwise.
86  bool DumpStopContext(Stream *s, bool show_fullpaths) const;
87
88  /// Check if a line entry object is valid.
89  ///
90  /// \return
91  ///     Returns \b true if the line entry contains a valid section
92  ///     offset address, file index, and line number, \b false
93  ///     otherwise.
94  bool IsValid() const;
95
96  /// Compare two LineEntry objects.
97  ///
98  /// \param[in] lhs
99  ///     The Left Hand Side const LineEntry object reference.
100  ///
101  /// \param[in] rhs
102  ///     The Right Hand Side const LineEntry object reference.
103  ///
104  /// \return
105  ///     \li -1 if lhs < rhs
106  ///     \li 0 if lhs == rhs
107  ///     \li 1 if lhs > rhs
108  static int Compare(const LineEntry &lhs, const LineEntry &rhs);
109
110  /// Give the range for this LineEntry + any additional LineEntries for this
111  /// same source line that are contiguous.
112  ///
113  /// A compiler may emit multiple line entries for a single source line,
114  /// e.g. to indicate subexpressions at different columns.  This method will
115  /// get the AddressRange for all of the LineEntries for this source line
116  /// that are contiguous.
117  //
118  /// Line entries with a line number of 0 are treated specially - these are
119  /// compiler-generated line table entries that the user did not write in
120  /// their source code, and we want to skip past in the debugger. If this
121  /// LineEntry is for line 32, and the following LineEntry is for line 0, we
122  /// will extend the range to include the AddressRange of the line 0
123  /// LineEntry (and it will include the range of the following LineEntries
124  /// that match either 32 or 0.)
125  ///
126  /// When \b include_inlined_functions is \b true inlined functions with
127  /// a call site at this LineEntry will also be included in the complete
128  /// range.
129  ///
130  /// If the initial LineEntry this method is called on is a line #0, only the
131  /// range of contiuous LineEntries with line #0 will be included in the
132  /// complete range.
133  ///
134  /// @param[in] include_inlined_functions
135  ///     Whether to include inlined functions at the same line or not.
136  ///
137  /// \return
138  ///     The contiguous AddressRange for this source line.
139  AddressRange
140  GetSameLineContiguousAddressRange(bool include_inlined_functions) const;
141
142  /// Apply file mappings from target.source-map to the LineEntry's file.
143  ///
144  /// \param[in] target_sp
145  ///     Shared pointer to the target this LineEntry belongs to.
146
147  void ApplyFileMappings(lldb::TargetSP target_sp);
148
149  // Member variables.
150  AddressRange range; ///< The section offset address range for this line entry.
151  FileSpec file; ///< The source file, possibly mapped by the target.source-map
152                 ///setting
153  FileSpec original_file; ///< The original source file, from debug info.
154  uint32_t line; ///< The source line number, or zero if there is no line number
155                 ///information.
156  uint16_t column; ///< The column number of the source line, or zero if there
157                   ///is no column information.
158  uint16_t is_start_of_statement : 1, ///< Indicates this entry is the beginning
159                                      ///of a statement.
160      is_start_of_basic_block : 1, ///< Indicates this entry is the beginning of
161                                   ///a basic block.
162      is_prologue_end : 1,   ///< Indicates this entry is one (of possibly many)
163                             ///where execution should be suspended for an entry
164                             ///breakpoint of a function.
165      is_epilogue_begin : 1, ///< Indicates this entry is one (of possibly many)
166                             ///where execution should be suspended for an exit
167                             ///breakpoint of a function.
168      is_terminal_entry : 1; ///< Indicates this entry is that of the first byte
169                             ///after the end of a sequence of target machine
170                             ///instructions.
171};
172
173/// Less than operator.
174///
175/// \param[in] lhs
176///     The Left Hand Side const LineEntry object reference.
177///
178/// \param[in] rhs
179///     The Right Hand Side const LineEntry object reference.
180///
181/// \return
182///     Returns \b true if lhs < rhs, false otherwise.
183bool operator<(const LineEntry &lhs, const LineEntry &rhs);
184
185} // namespace lldb_private
186
187#endif // liblldb_LineEntry_h_
188