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 78namespace llvm { 79class DiagnosticInfo; 80class raw_ostream; 81} 82 83namespace lld { 84 85llvm::raw_ostream &outs(); 86llvm::raw_ostream &errs(); 87 88enum class ErrorTag { LibNotFound, SymbolNotFound }; 89 90class ErrorHandler { 91public: 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 123private: 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. 145ErrorHandler &errorHandler(); 146 147void error(const Twine &msg); 148void error(const Twine &msg, ErrorTag tag, ArrayRef<StringRef> args); 149[[noreturn]] void fatal(const Twine &msg); 150void log(const Twine &msg); 151void message(const Twine &msg, llvm::raw_ostream &s = outs()); 152void warn(const Twine &msg); 153uint64_t errorCount(); 154 155[[noreturn]] void exitLld(int val); 156 157void diagnosticHandler(const llvm::DiagnosticInfo &di); 158void checkError(Error e); 159 160// check functions are convenient functions to strip errors 161// from error-or-value objects. 162template <class T> T check(ErrorOr<T> e) { 163 if (auto ec = e.getError()) 164 fatal(ec.message()); 165 return std::move(*e); 166} 167 168template <class T> T check(Expected<T> e) { 169 if (!e) 170 fatal(llvm::toString(e.takeError())); 171 return std::move(*e); 172} 173 174// Don't move from Expected wrappers around references. 175template <class T> T &check(Expected<T &> e) { 176 if (!e) 177 fatal(llvm::toString(e.takeError())); 178 return *e; 179} 180 181template <class T> 182T 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 188template <class T> 189T 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 195inline 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