1 // Copyright 2019 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef BASE_PROFILER_STACK_SAMPLING_PROFILER_TEST_UTIL_H_
6 #define BASE_PROFILER_STACK_SAMPLING_PROFILER_TEST_UTIL_H_
12 #include "base/base_export.h"
13 #include "base/functional/callback.h"
14 #include "base/memory/raw_ptr.h"
15 #include "base/memory/raw_ptr_exclusion.h"
16 #include "base/native_library.h"
17 #include "base/profiler/frame.h"
18 #include "base/profiler/sampling_profiler_thread_token.h"
19 #include "base/profiler/stack_sampling_profiler.h"
20 #include "base/strings/string_piece.h"
21 #include "base/synchronization/waitable_event.h"
22 #include "base/threading/platform_thread.h"
29 // A thread to target for profiling that will run the supplied closure.
30 class TargetThread : public PlatformThread::Delegate {
32 explicit TargetThread(OnceClosure to_run);
34 TargetThread(const TargetThread&) = delete;
35 TargetThread& operator=(const TargetThread&) = delete;
37 ~TargetThread() override;
42 // PlatformThread::Delegate:
43 void ThreadMain() override;
45 SamplingProfilerThreadToken thread_token() const { return thread_token_; }
48 SamplingProfilerThreadToken thread_token_ = {0};
50 PlatformThreadHandle target_thread_handle_;
53 // Addresses near the start and end of a function.
54 struct FunctionAddressRange {
55 // This field is not a raw_ptr<> because it was filtered by the rewriter for:
57 RAW_PTR_EXCLUSION const void* start;
58 raw_ptr<const void> end;
61 // Represents a stack unwind scenario to be sampled by the
62 // StackSamplingProfiler.
63 class UnwindScenario {
65 // A callback provided by the caller that sets up the unwind scenario, then
66 // calls into the passed closure to wait for a sample to be taken. Returns the
67 // address range of the function that sets up the unwind scenario. The passed
68 // closure will be null when invoked solely to obtain the address range.
69 using SetupFunction = RepeatingCallback<FunctionAddressRange(OnceClosure)>;
71 // Events to coordinate the sampling.
73 WaitableEvent ready_for_sample;
74 WaitableEvent sample_finished;
77 explicit UnwindScenario(const SetupFunction& setup_function);
80 UnwindScenario(const UnwindScenario&) = delete;
81 UnwindScenario& operator=(const UnwindScenario&) = delete;
83 // The address range of the innermost function that waits for the sample.
84 FunctionAddressRange GetWaitForSampleAddressRange() const;
86 // The address range of the provided setup function.
87 FunctionAddressRange GetSetupFunctionAddressRange() const;
89 // The address range of the outer function that indirectly invokes the setup
91 FunctionAddressRange GetOuterFunctionAddressRange() const;
93 // Executes the scenario.
94 void Execute(SampleEvents* events);
97 static FunctionAddressRange InvokeSetupFunction(
98 const SetupFunction& setup_function,
99 SampleEvents* events);
101 static FunctionAddressRange WaitForSample(SampleEvents* events);
103 const SetupFunction setup_function_;
106 class TestModule : public ModuleCache::Module {
108 explicit TestModule(uintptr_t base_address = 0,
110 bool is_native = true)
111 : base_address_(base_address), size_(size), is_native_(is_native) {}
113 uintptr_t GetBaseAddress() const override;
114 std::string GetId() const override;
115 FilePath GetDebugBasename() const override;
116 size_t GetSize() const override;
117 bool IsNative() const override;
119 void set_id(const std::string& id) { id_ = id; }
120 void set_debug_basename(const FilePath& basename) {
121 debug_basename_ = basename;
125 const uintptr_t base_address_;
127 const bool is_native_;
129 FilePath debug_basename_;
132 bool operator==(const Frame& a, const Frame& b);
134 // UnwindScenario setup function that calls into |wait_for_sample| without doing
135 // any special unwinding setup, to exercise the "normal" unwind scenario.
136 FunctionAddressRange CallWithPlainFunction(OnceClosure wait_for_sample);
138 // Calls into |wait_for_sample| after using alloca(), to test unwinding with a
140 FunctionAddressRange CallWithAlloca(OnceClosure wait_for_sample);
142 // Calls into |wait_for_sample| through a function within another library, to
143 // test unwinding through multiple modules and scenarios involving unloaded
145 FunctionAddressRange CallThroughOtherLibrary(NativeLibrary library,
146 OnceClosure wait_for_sample);
148 // The callback to perform profiling on the provided thread.
149 using ProfileCallback = OnceCallback<void(SamplingProfilerThreadToken)>;
151 // Executes |profile_callback| while running |scenario| on the target
152 // thread. Performs all necessary target thread startup and shutdown work before
154 void WithTargetThread(UnwindScenario* scenario,
155 ProfileCallback profile_callback);
157 using UnwinderFactory = OnceCallback<std::unique_ptr<Unwinder>()>;
159 // Returns the sample seen when taking one sample of |scenario|.
160 std::vector<Frame> SampleScenario(
161 UnwindScenario* scenario,
162 ModuleCache* module_cache,
163 UnwinderFactory aux_unwinder_factory = UnwinderFactory());
165 // Formats a sample into a string that can be output for test diagnostics.
166 std::string FormatSampleForDiagnosticOutput(const std::vector<Frame>& sample);
168 // Expects that the stack contains the functions with the specified address
169 // ranges, in the specified order.
170 void ExpectStackContains(const std::vector<Frame>& stack,
171 const std::vector<FunctionAddressRange>& functions);
173 // Expects that the stack contains the function names in the specified order.
174 void ExpectStackContainsNames(const std::vector<Frame>& stack,
175 const std::vector<std::string>& function_names);
177 // Expects that the stack does not contain the functions with the specified
179 void ExpectStackDoesNotContain(
180 const std::vector<Frame>& stack,
181 const std::vector<FunctionAddressRange>& functions);
183 // Load test library with given name.
184 NativeLibrary LoadTestLibrary(StringPiece library_name);
186 // Loads the other library, which defines a function to be called in the
187 // WITH_OTHER_LIBRARY configuration.
188 NativeLibrary LoadOtherLibrary();
190 uintptr_t GetAddressInOtherLibrary(NativeLibrary library);
192 // Creates a list of core unwinders required for StackSamplingProfilerTest.
193 // This is useful notably on Android, which requires ChromeUnwinderAndroid in
194 // addition to the native one.
195 StackSamplingProfiler::UnwindersFactory CreateCoreUnwindersFactoryForTesting(
196 ModuleCache* module_cache);
200 #endif // BASE_PROFILER_STACK_SAMPLING_PROFILER_TEST_UTIL_H_