1 //===-- llvm/Debuginfod/Debuginfod.h - Debuginfod client --------*- 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 /// \file 10 /// This file contains several declarations for the debuginfod client and 11 /// server. The client functions are getDefaultDebuginfodUrls, 12 /// getCachedOrDownloadArtifact, and several convenience functions for specific 13 /// artifact types: getCachedOrDownloadSource, getCachedOrDownloadExecutable, 14 /// and getCachedOrDownloadDebuginfo. For the server, this file declares the 15 /// DebuginfodLogEntry and DebuginfodServer structs, as well as the 16 /// DebuginfodLog, DebuginfodCollection classes. 17 /// 18 //===----------------------------------------------------------------------===// 19 20 #ifndef LLVM_DEBUGINFOD_DEBUGINFOD_H 21 #define LLVM_DEBUGINFOD_DEBUGINFOD_H 22 23 #include "HTTPServer.h" 24 25 #include "llvm/ADT/StringMap.h" 26 #include "llvm/ADT/StringRef.h" 27 #include "llvm/Object/BuildID.h" 28 #include "llvm/Support/Error.h" 29 #include "llvm/Support/MemoryBuffer.h" 30 #include "llvm/Support/Mutex.h" 31 #include "llvm/Support/RWMutex.h" 32 #include "llvm/Support/Timer.h" 33 34 #include <chrono> 35 #include <condition_variable> 36 #include <optional> 37 #include <queue> 38 39 namespace llvm { 40 41 /// Returns false if a debuginfod lookup can be determined to have no chance of 42 /// succeeding. 43 bool canUseDebuginfod(); 44 45 /// Finds default array of Debuginfod server URLs by checking DEBUGINFOD_URLS 46 /// environment variable. 47 SmallVector<StringRef> getDefaultDebuginfodUrls(); 48 49 /// Returns the cache key for a given debuginfod URL path. 50 std::string getDebuginfodCacheKey(StringRef UrlPath); 51 52 /// Sets the list of debuginfod server URLs to query. This overrides the 53 /// environment variable DEBUGINFOD_URLS. 54 void setDefaultDebuginfodUrls(const SmallVector<StringRef> &URLs); 55 56 /// Finds a default local file caching directory for the debuginfod client, 57 /// first checking DEBUGINFOD_CACHE_PATH. 58 Expected<std::string> getDefaultDebuginfodCacheDirectory(); 59 60 /// Finds a default timeout for debuginfod HTTP requests. Checks 61 /// DEBUGINFOD_TIMEOUT environment variable, default is 90 seconds (90000 ms). 62 std::chrono::milliseconds getDefaultDebuginfodTimeout(); 63 64 /// Get the full URL path for a source request of a given BuildID and file 65 /// path. 66 std::string getDebuginfodSourceUrlPath(object::BuildIDRef ID, 67 StringRef SourceFilePath); 68 69 /// Fetches a specified source file by searching the default local cache 70 /// directory and server URLs. 71 Expected<std::string> getCachedOrDownloadSource(object::BuildIDRef ID, 72 StringRef SourceFilePath); 73 74 /// Get the full URL path for an executable request of a given BuildID. 75 std::string getDebuginfodExecutableUrlPath(object::BuildIDRef ID); 76 77 /// Fetches an executable by searching the default local cache directory and 78 /// server URLs. 79 Expected<std::string> getCachedOrDownloadExecutable(object::BuildIDRef ID); 80 81 /// Get the full URL path for a debug binary request of a given BuildID. 82 std::string getDebuginfodDebuginfoUrlPath(object::BuildIDRef ID); 83 84 /// Fetches a debug binary by searching the default local cache directory and 85 /// server URLs. 86 Expected<std::string> getCachedOrDownloadDebuginfo(object::BuildIDRef ID); 87 88 /// Fetches any debuginfod artifact using the default local cache directory and 89 /// server URLs. 90 Expected<std::string> getCachedOrDownloadArtifact(StringRef UniqueKey, 91 StringRef UrlPath); 92 93 /// Fetches any debuginfod artifact using the specified local cache directory, 94 /// server URLs, and request timeout (in milliseconds). If the artifact is 95 /// found, uses the UniqueKey for the local cache file. 96 Expected<std::string> getCachedOrDownloadArtifact( 97 StringRef UniqueKey, StringRef UrlPath, StringRef CacheDirectoryPath, 98 ArrayRef<StringRef> DebuginfodUrls, std::chrono::milliseconds Timeout); 99 100 class ThreadPoolInterface; 101 102 struct DebuginfodLogEntry { 103 std::string Message; 104 DebuginfodLogEntry() = default; 105 DebuginfodLogEntry(const Twine &Message); 106 }; 107 108 class DebuginfodLog { 109 std::mutex QueueMutex; 110 std::condition_variable QueueCondition; 111 std::queue<DebuginfodLogEntry> LogEntryQueue; 112 113 public: 114 // Adds a log entry to end of the queue. 115 void push(DebuginfodLogEntry Entry); 116 // Adds a log entry to end of the queue. 117 void push(const Twine &Message); 118 // Blocks until there are log entries in the queue, then pops and returns the 119 // first one. 120 DebuginfodLogEntry pop(); 121 }; 122 123 /// Tracks a collection of debuginfod artifacts on the local filesystem. 124 class DebuginfodCollection { 125 SmallVector<std::string, 1> Paths; 126 sys::RWMutex BinariesMutex; 127 StringMap<std::string> Binaries; 128 sys::RWMutex DebugBinariesMutex; 129 StringMap<std::string> DebugBinaries; 130 Error findBinaries(StringRef Path); 131 Expected<std::optional<std::string>> getDebugBinaryPath(object::BuildIDRef); 132 Expected<std::optional<std::string>> getBinaryPath(object::BuildIDRef); 133 // If the collection has not been updated since MinInterval, call update() and 134 // return true. Otherwise return false. If update returns an error, return the 135 // error. 136 Expected<bool> updateIfStale(); 137 DebuginfodLog &Log; 138 ThreadPoolInterface &Pool; 139 Timer UpdateTimer; 140 sys::Mutex UpdateMutex; 141 142 // Minimum update interval, in seconds, for on-demand updates triggered when a 143 // build-id is not found. 144 double MinInterval; 145 146 public: 147 DebuginfodCollection(ArrayRef<StringRef> Paths, DebuginfodLog &Log, 148 ThreadPoolInterface &Pool, double MinInterval); 149 Error update(); 150 Error updateForever(std::chrono::milliseconds Interval); 151 Expected<std::string> findDebugBinaryPath(object::BuildIDRef); 152 Expected<std::string> findBinaryPath(object::BuildIDRef); 153 }; 154 155 struct DebuginfodServer { 156 HTTPServer Server; 157 DebuginfodLog &Log; 158 DebuginfodCollection &Collection; 159 DebuginfodServer(DebuginfodLog &Log, DebuginfodCollection &Collection); 160 }; 161 162 } // end namespace llvm 163 164 #endif 165