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 | |