1 | //===- ErrorHandler.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 | // We designed lld's error handlers with the following goals in mind: |
10 | // |
11 | // - Errors can occur at any place where we handle user input, but we don't |
12 | // want them to affect the normal execution path too much. Ideally, |
13 | // handling errors should be as simple as reporting them and exit (but |
14 | // without actually doing exit). |
15 | // |
16 | // In particular, the design to wrap all functions that could fail with |
17 | // ErrorOr<T> is rejected because otherwise we would have to wrap a large |
18 | // number of functions in lld with ErrorOr. With that approach, if some |
19 | // function F can fail, not only F but all functions that transitively call |
20 | // F have to be wrapped with ErrorOr. That seemed too much. |
21 | // |
22 | // - Finding only one error at a time is not sufficient. We want to find as |
23 | // many errors as possible with one execution of the linker. That means the |
24 | // linker needs to keep running after a first error and give up at some |
25 | // checkpoint (beyond which it would find cascading, false errors caused by |
26 | // the previous errors). |
27 | // |
28 | // - We want a simple interface to report errors. Unlike Clang, the data we |
29 | // handle is compiled binary, so we don't need an error reporting mechanism |
30 | // that's as sophisticated as the one that Clang has. |
31 | // |
32 | // The current lld's error handling mechanism is simple: |
33 | // |
34 | // - When you find an error, report it using error() and continue as far as |
35 | // you can. An internal error counter is incremented by one every time you |
36 | // call error(). |
37 | // |
38 | // A common idiom to handle an error is calling error() and then returning |
39 | // a reasonable default value. For example, if your function handles a |
40 | // user-supplied alignment value, and if you find an invalid alignment |
41 | // (e.g. 17 which is not 2^n), you may report it using error() and continue |
42 | // as if it were alignment 1 (which is the simplest reasonable value). |
43 | // |
44 | // Note that you should not continue with an invalid value; that breaks the |
45 | // internal consistency. You need to maintain all variables have some sane |
46 | // value even after an error occurred. So, when you have to continue with |
47 | // some value, always use a dummy value. |
48 | // |
49 | // - Find a reasonable checkpoint at where you want to stop the linker, and |
50 | // add code to return from the function if errorCount() > 0. In most cases, |
51 | // a checkpoint already exists, so you don't need to do anything for this. |
52 | // |
53 | // This interface satisfies all the goals that we mentioned above. |
54 | // |
55 | // You should never call fatal() except for reporting a corrupted input file. |
56 | // fatal() immediately terminates the linker, so the function is not desirable |
57 | // if you are using lld as a subroutine in other program, and with that you |
58 | // can find only one error at a time. |
59 | // |
60 | // warn() doesn't do anything but printing out a given message. |
61 | // |
62 | // It is not recommended to use llvm::outs() or lld::errs() directly in lld |
63 | // because they are not thread-safe. The functions declared in this file are |
64 | // thread-safe. |
65 | // |
66 | //===----------------------------------------------------------------------===// |
67 | |
68 | #ifndef LLD_COMMON_ERRORHANDLER_H |
69 | #define LLD_COMMON_ERRORHANDLER_H |
70 | |
71 | #include "lld/Common/LLVM.h" |
72 | |
73 | #include "llvm/ADT/STLExtras.h" |
74 | #include "llvm/Support/Error.h" |
75 | #include "llvm/Support/FileOutputBuffer.h" |
76 | #include <mutex> |
77 | |
78 | namespace llvm { |
79 | class DiagnosticInfo; |
80 | class raw_ostream; |
81 | } |
82 | |
83 | namespace lld { |
84 | |
85 | llvm::raw_ostream &outs(); |
86 | llvm::raw_ostream &errs(); |
87 | |
88 | enum class ErrorTag { LibNotFound, SymbolNotFound }; |
89 | |
90 | class ErrorHandler { |
91 | public: |
92 | ~ErrorHandler(); |
93 | |
94 | void initialize(llvm::raw_ostream &stdoutOS, llvm::raw_ostream &stderrOS, |
95 | bool exitEarly, bool disableOutput); |
96 | |
97 | uint64_t errorCount = 0; |
98 | uint64_t errorLimit = 20; |
99 | StringRef errorLimitExceededMsg = "too many errors emitted, stopping now" ; |
100 | StringRef errorHandlingScript; |
101 | StringRef logName = "lld" ; |
102 | bool exitEarly = true; |
103 | bool fatalWarnings = false; |
104 | bool suppressWarnings = false; |
105 | bool verbose = false; |
106 | bool vsDiagnostics = false; |
107 | bool disableOutput = false; |
108 | std::function<void()> cleanupCallback; |
109 | |
110 | void error(const Twine &msg); |
111 | void error(const Twine &msg, ErrorTag tag, ArrayRef<StringRef> args); |
112 | [[noreturn]] void fatal(const Twine &msg); |
113 | void log(const Twine &msg); |
114 | void message(const Twine &msg, llvm::raw_ostream &s); |
115 | void warn(const Twine &msg); |
116 | |
117 | raw_ostream &outs(); |
118 | raw_ostream &errs(); |
119 | void flushStreams(); |
120 | |
121 | std::unique_ptr<llvm::FileOutputBuffer> outputBuffer; |
122 | |
123 | private: |
124 | using Colors = raw_ostream::Colors; |
125 | |
126 | std::string getLocation(const Twine &msg); |
127 | void reportDiagnostic(StringRef location, Colors c, StringRef diagKind, |
128 | const Twine &msg); |
129 | |
130 | // We want to separate multi-line messages with a newline. `sep` is "\n" |
131 | // if the last messages was multi-line. Otherwise "". |
132 | llvm::StringRef sep; |
133 | |
134 | // We wrap stdout and stderr so that you can pass alternative stdout/stderr as |
135 | // arguments to lld::*::link() functions. Since lld::outs() or lld::errs() can |
136 | // be indirectly called from multiple threads, we protect them using a mutex. |
137 | // In the future, we plan on supporting several concurrent linker contexts, |
138 | // which explains why the mutex is not a global but part of this context. |
139 | std::mutex mu; |
140 | llvm::raw_ostream *stdoutOS{}; |
141 | llvm::raw_ostream *stderrOS{}; |
142 | }; |
143 | |
144 | /// Returns the default error handler. |
145 | ErrorHandler &errorHandler(); |
146 | |
147 | void error(const Twine &msg); |
148 | void error(const Twine &msg, ErrorTag tag, ArrayRef<StringRef> args); |
149 | [[noreturn]] void fatal(const Twine &msg); |
150 | void log(const Twine &msg); |
151 | void message(const Twine &msg, llvm::raw_ostream &s = outs()); |
152 | void warn(const Twine &msg); |
153 | uint64_t errorCount(); |
154 | |
155 | [[noreturn]] void exitLld(int val); |
156 | |
157 | void diagnosticHandler(const llvm::DiagnosticInfo &di); |
158 | void checkError(Error e); |
159 | |
160 | // check functions are convenient functions to strip errors |
161 | // from error-or-value objects. |
162 | template <class T> T check(ErrorOr<T> e) { |
163 | if (auto ec = e.getError()) |
164 | fatal(ec.message()); |
165 | return std::move(*e); |
166 | } |
167 | |
168 | template <class T> T check(Expected<T> e) { |
169 | if (!e) |
170 | fatal(llvm::toString(E: e.takeError())); |
171 | return std::move(*e); |
172 | } |
173 | |
174 | // Don't move from Expected wrappers around references. |
175 | template <class T> T &check(Expected<T &> e) { |
176 | if (!e) |
177 | fatal(llvm::toString(E: e.takeError())); |
178 | return *e; |
179 | } |
180 | |
181 | template <class T> |
182 | T check2(ErrorOr<T> e, llvm::function_ref<std::string()> prefix) { |
183 | if (auto ec = e.getError()) |
184 | fatal(prefix() + ": " + ec.message()); |
185 | return std::move(*e); |
186 | } |
187 | |
188 | template <class T> |
189 | T check2(Expected<T> e, llvm::function_ref<std::string()> prefix) { |
190 | if (!e) |
191 | fatal(prefix() + ": " + toString(e.takeError())); |
192 | return std::move(*e); |
193 | } |
194 | |
195 | inline std::string toString(const Twine &s) { return s.str(); } |
196 | |
197 | // To evaluate the second argument lazily, we use C macro. |
198 | #define CHECK(E, S) check2((E), [&] { return toString(S); }) |
199 | |
200 | } // namespace lld |
201 | |
202 | #endif |
203 | |