tools/profiler/UnwinderThread2.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef MOZ_UNWINDER_THREAD_2_H
   7 #define MOZ_UNWINDER_THREAD_2_H
   8
   9 #include "GeckoProfilerImpl.h"
  10 #include "ProfileEntry.h"
  11
  12 #include "PlatformMacros.h"
  13 #if defined(SPS_OS_android) || defined(SPS_OS_linux)
  14 # include "LulMain.h"
  15 #endif
  16
  17 /* Top level exports of UnwinderThread.cpp. */
  18
  19 // Abstract type.  A buffer which is used to transfer information between
  20 // the sampled thread(s) and the unwinder thread(s).
  21 typedef
  22   struct _UnwinderThreadBuffer
  23   UnwinderThreadBuffer;
  24
  25 // RUNS IN SIGHANDLER CONTEXT
  26 // Called in the sampled thread (signal) context.  Adds a ProfileEntry
  27 // into an UnwinderThreadBuffer that the thread has previously obtained
  28 // by a call to utb__acquire_empty_buffer.
  29 void utb__addEntry(/*MOD*/UnwinderThreadBuffer* utb,
  30                    ProfileEntry ent);
  31
  32 // Create the unwinder thread.  At the moment there can be only one.
  33 void uwt__init();
  34
  35 // Request the unwinder thread to exit, and wait until it has done so.
  36 // This must be called before stopping the profiler because we hold a
  37 // reference to the profile which is owned by the profiler.
  38 void uwt__stop();
  39
  40 // Release the unwinder resources. This must be called after profiling
  41 // has stop. At this point we know the profiler doesn't hold any buffer
  42 // and can safely release any resources.
  43 void uwt__deinit();
  44
  45 // Registers a sampler thread for profiling.  Threads must be
  46 // registered before calls to call utb__acquire_empty_buffer or
  47 // utb__release_full_buffer have any effect.  If stackTop is
  48 // nullptr, the call is ignored.
  49 void uwt__register_thread_for_profiling(void* stackTop);
  50
  51 // Deregister a sampler thread for profiling.
  52 void uwt__unregister_thread_for_profiling();
  53
  54 // RUNS IN SIGHANDLER CONTEXT
  55 // Called in the sampled thread (signal) context.  Get an empty buffer
  56 // into which ProfileEntries can be put.  It may return nullptr if no
  57 // empty buffers can be found, which will be the case if the unwinder
  58 // thread(s) have fallen behind for some reason.  In this case the
  59 // sampled thread must simply give up and return from the signal
  60 // handler immediately, else it risks deadlock.
  61 //
  62 // If the calling thread has not previously registered itself for
  63 // profiling via uwt__register_thread_for_profiling, this routine
  64 // returns nullptr.
  65 UnwinderThreadBuffer* uwt__acquire_empty_buffer();
  66
  67 // RUNS IN SIGHANDLER CONTEXT
  68 // Called in the sampled thread (signal) context.  Release a buffer
  69 // that the sampled thread has acquired, handing the contents to
  70 // the unwinder thread, and, if necessary, passing sufficient
  71 // information (stack top chunk, + registers) to also do a native
  72 // unwind.  If 'ucV' is nullptr, no native unwind is done.  If non-nullptr,
  73 // it is assumed to point to a ucontext_t* that holds the initial
  74 // register state for the unwind.  The results of all of this are
  75 // dumped into |aProfile| (by the unwinder thread, not the calling thread).
  76 void uwt__release_full_buffer(ThreadProfile* aProfile,
  77                               UnwinderThreadBuffer* utb,
  78                               void* /* ucontext_t*, really */ ucV);
  79
  80 struct LinkedUWTBuffer;
  81
  82 // Get an empty buffer for synchronous unwinding.
  83 // This function is NOT signal-safe.
  84 LinkedUWTBuffer* utb__acquire_sync_buffer(void* stackTop);
  85
  86 void utb__finish_sync_buffer(ThreadProfile* aProfile,
  87                              UnwinderThreadBuffer* utb,
  88                              void* /* ucontext_t*, really */ ucV);
  89
  90 // Free an empty buffer that was previously allocated by
  91 // utb__acquire_sync_buffer.
  92 void utb__release_sync_buffer(LinkedUWTBuffer* utb);
  93
  94 // Unwind complete, mark a synchronous unwind buffer as empty
  95 void utb__end_sync_buffer_unwind(LinkedUWTBuffer* utb);
  96
  97 // This typedef must match uwt__release_full_buffer and uwt__finish_sync_buffer
  98 typedef void (*UTB_RELEASE_FUNC)(ThreadProfile*,UnwinderThreadBuffer*,void*);
  99
 100 #if defined(SPS_OS_android) || defined(SPS_OS_linux)
 101 // Notify |aLUL| of the objects in the current process, so as to get
 102 // it to read unwind data for them.  This has to be externally visible
 103 // so it can be used in LUL unit tests, tools/profiler/tests/gtest/LulTest.cpp.
 104 void read_procmaps(lul::LUL* aLUL);
 105 #endif
 106
 107 #endif /* ndef MOZ_UNWINDER_THREAD_2_H */