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] show_file
46  ///     If \b true, display the filename with the line entry which
47  ///     requires that the compile unit object \a comp_unit be a
48  ///     valid pointer.
49  ///
50  /// \param[in] style
51  ///     The display style for the section offset address.
52  ///
53  /// \return
54  ///     Returns \b true if the address was able to be displayed
55  ///     using \a style. File and load addresses may be unresolved
56  ///     and it may not be possible to display a valid address value.
57  ///     Returns \b false if the address was not able to be properly
58  ///     dumped.
59  ///
60  /// \see Address::DumpStyle
61  bool Dump(Stream *s, Target *target, bool show_file, Address::DumpStyle style,
62            Address::DumpStyle fallback_style, bool show_range) const;
63
64  bool GetDescription(Stream *s, lldb::DescriptionLevel level, CompileUnit *cu,
65                      Target *target, bool show_address_only) const;
66
67  /// Dumps information specific to a process that stops at this line entry to
68  /// the supplied stream \a s.
69  ///
70  /// \param[in] s
71  ///     The stream to which to dump the object description.
72  ///
73  /// \return
74  ///     Returns \b true if the file and line were properly dumped,
75  ///     \b false otherwise.
76  bool DumpStopContext(Stream *s, bool show_fullpaths) const;
77
78  /// Check if a line entry object is valid.
79  ///
80  /// \return
81  ///     Returns \b true if the line entry contains a valid section
82  ///     offset address, file index, and line number, \b false
83  ///     otherwise.
84  bool IsValid() const;
85
86  /// Compare two LineEntry objects.
87  ///
88  /// \param[in] lhs
89  ///     The Left Hand Side const LineEntry object reference.
90  ///
91  /// \param[in] rhs
92  ///     The Right Hand Side const LineEntry object reference.
93  ///
94  /// \return
95  ///     -1 if lhs < rhs
96  ///     0 if lhs == rhs
97  ///     1 if lhs > rhs
98  static int Compare(const LineEntry &lhs, const LineEntry &rhs);
99
100  /// Give the range for this LineEntry + any additional LineEntries for this
101  /// same source line that are contiguous.
102  ///
103  /// A compiler may emit multiple line entries for a single source line,
104  /// e.g. to indicate subexpressions at different columns.  This method will
105  /// get the AddressRange for all of the LineEntries for this source line
106  /// that are contiguous.
107  //
108  /// Line entries with a line number of 0 are treated specially - these are
109  /// compiler-generated line table entries that the user did not write in
110  /// their source code, and we want to skip past in the debugger. If this
111  /// LineEntry is for line 32, and the following LineEntry is for line 0, we
112  /// will extend the range to include the AddressRange of the line 0
113  /// LineEntry (and it will include the range of the following LineEntries
114  /// that match either 32 or 0.)
115  ///
116  /// When \b include_inlined_functions is \b true inlined functions with
117  /// a call site at this LineEntry will also be included in the complete
118  /// range.
119  ///
120  /// If the initial LineEntry this method is called on is a line #0, only the
121  /// range of contiuous LineEntries with line #0 will be included in the
122  /// complete range.
123  ///
124  /// @param[in] include_inlined_functions
125  ///     Whether to include inlined functions at the same line or not.
126  ///
127  /// \return
128  ///     The contiguous AddressRange for this source line.
129  AddressRange
130  GetSameLineContiguousAddressRange(bool include_inlined_functions) const;
131
132  /// Apply file mappings from target.source-map to the LineEntry's file.
133  ///
134  /// \param[in] target_sp
135  ///     Shared pointer to the target this LineEntry belongs to.
136  void ApplyFileMappings(lldb::TargetSP target_sp);
137
138  // Member variables.
139  AddressRange range; ///< The section offset address range for this line entry.
140  FileSpec file; ///< The source file, possibly mapped by the target.source-map
141                 ///setting
142  FileSpec original_file; ///< The original source file, from debug info.
143  uint32_t line; ///< The source line number, or zero if there is no line number
144                 ///information.
145  uint16_t column; ///< The column number of the source line, or zero if there
146                   ///is no column information.
147  uint16_t is_start_of_statement : 1, ///< Indicates this entry is the beginning
148                                      ///of a statement.
149      is_start_of_basic_block : 1, ///< Indicates this entry is the beginning of
150                                   ///a basic block.
151      is_prologue_end : 1,   ///< Indicates this entry is one (of possibly many)
152                             ///where execution should be suspended for an entry
153                             ///breakpoint of a function.
154      is_epilogue_begin : 1, ///< Indicates this entry is one (of possibly many)
155                             ///where execution should be suspended for an exit
156                             ///breakpoint of a function.
157      is_terminal_entry : 1; ///< Indicates this entry is that of the first byte
158                             ///after the end of a sequence of target machine
159                             ///instructions.
160};
161
162/// Less than operator.
163///
164/// \param[in] lhs
165///     The Left Hand Side const LineEntry object reference.
166///
167/// \param[in] rhs
168///     The Right Hand Side const LineEntry object reference.
169///
170/// \return
171///     Returns \b true if lhs < rhs, false otherwise.
172bool operator<(const LineEntry &lhs, const LineEntry &rhs);
173
174} // namespace lldb_private
175
176#endif // liblldb_LineEntry_h_
177