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 77 namespace llvm { 78 class DiagnosticInfo; 79 class raw_ostream; 80 } 81 82 namespace lld { 83 84 // We wrap stdout and stderr so that you can pass alternative stdout/stderr as 85 // arguments to lld::*::link() functions. 86 extern llvm::raw_ostream *stdoutOS; 87 extern llvm::raw_ostream *stderrOS; 88 89 llvm::raw_ostream &outs(); 90 llvm::raw_ostream &errs(); 91 92 class ErrorHandler { 93 public: 94 uint64_t errorCount = 0; 95 uint64_t errorLimit = 20; 96 StringRef errorLimitExceededMsg = "too many errors emitted, stopping now"; 97 StringRef logName = "lld"; 98 bool exitEarly = true; 99 bool fatalWarnings = false; 100 bool verbose = false; 101 bool vsDiagnostics = false; 102 103 void error(const Twine &msg); 104 LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg); 105 void log(const Twine &msg); 106 void message(const Twine &msg); 107 void warn(const Twine &msg); 108 109 std::unique_ptr<llvm::FileOutputBuffer> outputBuffer; 110 111 private: 112 using Colors = raw_ostream::Colors; 113 114 std::string getLocation(const Twine &msg); 115 }; 116 117 /// Returns the default error handler. 118 ErrorHandler &errorHandler(); 119 120 inline void error(const Twine &msg) { errorHandler().error(msg); } 121 inline LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg) { 122 errorHandler().fatal(msg); 123 } 124 inline void log(const Twine &msg) { errorHandler().log(msg); } 125 inline void message(const Twine &msg) { errorHandler().message(msg); } 126 inline void warn(const Twine &msg) { errorHandler().warn(msg); } 127 inline uint64_t errorCount() { return errorHandler().errorCount; } 128 129 LLVM_ATTRIBUTE_NORETURN void exitLld(int val); 130 131 void diagnosticHandler(const llvm::DiagnosticInfo &di); 132 void checkError(Error e); 133 134 // check functions are convenient functions to strip errors 135 // from error-or-value objects. 136 template <class T> T check(ErrorOr<T> e) { 137 if (auto ec = e.getError()) 138 fatal(ec.message()); 139 return std::move(*e); 140 } 141 142 template <class T> T check(Expected<T> e) { 143 if (!e) 144 fatal(llvm::toString(e.takeError())); 145 return std::move(*e); 146 } 147 148 template <class T> 149 T check2(ErrorOr<T> e, llvm::function_ref<std::string()> prefix) { 150 if (auto ec = e.getError()) 151 fatal(prefix() + ": " + ec.message()); 152 return std::move(*e); 153 } 154 155 template <class T> 156 T check2(Expected<T> e, llvm::function_ref<std::string()> prefix) { 157 if (!e) 158 fatal(prefix() + ": " + toString(e.takeError())); 159 return std::move(*e); 160 } 161 162 inline std::string toString(const Twine &s) { return s.str(); } 163 164 // To evaluate the second argument lazily, we use C macro. 165 #define CHECK(E, S) check2((E), [&] { return toString(S); }) 166 167 } // namespace lld 168 169 #endif 170