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 ThreadPoolInterface;
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 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
146public:
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
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

source code of llvm/include/llvm/Debuginfod/Debuginfod.h