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 39namespace llvm { 40 41/// Returns false if a debuginfod lookup can be determined to have no chance of 42/// succeeding. 43bool canUseDebuginfod(); 44 45/// Finds default array of Debuginfod server URLs by checking DEBUGINFOD_URLS 46/// environment variable. 47SmallVector<StringRef> getDefaultDebuginfodUrls(); 48 49/// Returns the cache key for a given debuginfod URL path. 50std::string getDebuginfodCacheKey(StringRef UrlPath); 51 52/// Sets the list of debuginfod server URLs to query. This overrides the 53/// environment variable DEBUGINFOD_URLS. 54void setDefaultDebuginfodUrls(const SmallVector<StringRef> &URLs); 55 56/// Finds a default local file caching directory for the debuginfod client, 57/// first checking DEBUGINFOD_CACHE_PATH. 58Expected<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). 62std::chrono::milliseconds getDefaultDebuginfodTimeout(); 63 64/// Get the full URL path for a source request of a given BuildID and file 65/// path. 66std::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. 71Expected<std::string> getCachedOrDownloadSource(object::BuildIDRef ID, 72 StringRef SourceFilePath); 73 74/// Get the full URL path for an executable request of a given BuildID. 75std::string getDebuginfodExecutableUrlPath(object::BuildIDRef ID); 76 77/// Fetches an executable by searching the default local cache directory and 78/// server URLs. 79Expected<std::string> getCachedOrDownloadExecutable(object::BuildIDRef ID); 80 81/// Get the full URL path for a debug binary request of a given BuildID. 82std::string getDebuginfodDebuginfoUrlPath(object::BuildIDRef ID); 83 84/// Fetches a debug binary by searching the default local cache directory and 85/// server URLs. 86Expected<std::string> getCachedOrDownloadDebuginfo(object::BuildIDRef ID); 87 88/// Fetches any debuginfod artifact using the default local cache directory and 89/// server URLs. 90Expected<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. 96Expected<std::string> getCachedOrDownloadArtifact( 97 StringRef UniqueKey, StringRef UrlPath, StringRef CacheDirectoryPath, 98 ArrayRef<StringRef> DebuginfodUrls, std::chrono::milliseconds Timeout); 99 100class ThreadPool; 101 102struct DebuginfodLogEntry { 103 std::string Message; 104 DebuginfodLogEntry() = default; 105 DebuginfodLogEntry(const Twine &Message); 106}; 107 108class DebuginfodLog { 109 std::mutex QueueMutex; 110 std::condition_variable QueueCondition; 111 std::queue<DebuginfodLogEntry> LogEntryQueue; 112 113public: 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. 124class 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 ThreadPool &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 146public: 147 DebuginfodCollection(ArrayRef<StringRef> Paths, DebuginfodLog &Log, 148 ThreadPool &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 155struct 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