The Tor Browser: tools/profiler/LulMain.h@97036ab72558 (annotated)

tools/profiler/LulMain.h@97036ab72558 (annotated)

tools/profiler/LulMain.h

Tue, 06 Jan 2015 21:39:09 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Tue, 06 Jan 2015 21:39:09 +0100
branch: TOR_BUG_9701
changeset 8: 97036ab72558
permissions: -rw-r--r--

Conditionally force memory storage according to privacy.thirdparty.isolate;
This solves Tor bug #9701, complying with disk avoidance documented in
https://www.torproject.org/projects/torbrowser/design/#disk-avoidance.

 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 #ifndef LulMain_h
 #define LulMain_h
 #include <pthread.h>   // pthread_t
 #include <map>
 #include "LulPlatformMacros.h"
 #include "LulRWLock.h"
 // LUL: A Lightweight Unwind Library.
 // This file provides the end-user (external) interface for LUL.
 // Some comments about naming in the implementation.  These are safe
 // to ignore if you are merely using LUL, but are important if you
 // hack on its internals.
 //
 // Debuginfo readers in general have tended to use the word "address"
 // to mean several different things.  This sometimes makes them
 // difficult to understand and maintain.  LUL tries hard to avoid
 // using the word "address" and instead uses the following more
 // precise terms:
 //
 // * SVMA ("Stated Virtual Memory Address"): this is an address of a
 //   symbol (etc) as it is stated in the symbol table, or other
 //   metadata, of an object.  Such values are typically small and
 //   start from zero or thereabouts, unless the object has been
 //   prelinked.
 //
 // * AVMA ("Actual Virtual Memory Address"): this is the address of a
 //   symbol (etc) in a running process, that is, once the associated
 //   object has been mapped into a process.  Such values are typically
 //   much larger than SVMAs, since objects can get mapped arbitrarily
 //   far along the address space.
 //
 // * "Bias": the difference between AVMA and SVMA for a given symbol
 //   (specifically, AVMA - SVMA).  The bias is always an integral
 //   number of pages.  Once we know the bias for a given object's
 //   text section (for example), we can compute the AVMAs of all of
 //   its text symbols by adding the bias to their SVMAs.
 //
 // * "Image address": typically, to read debuginfo from an object we
 //   will temporarily mmap in the file so as to read symbol tables
 //   etc.  Addresses in this temporary mapping are called "Image
 //   addresses".  Note that the temporary mapping is entirely
 //   unrelated to the mappings of the file that the dynamic linker
 //   must perform merely in order to get the program to run.  Hence
 //   image addresses are unrelated to either SVMAs or AVMAs.
 namespace lul {
 // A machine word plus validity tag.
 class TaggedUWord {
 public:
   // Construct a valid one.
   TaggedUWord(uintptr_t w)
     : mValue(w)
     , mValid(true)
   {}
   // Construct an invalid one.
   TaggedUWord()
     : mValue(0)
     , mValid(false)
   {}
   // Add in a second one.
   void Add(TaggedUWord other) {
     if (mValid && other.Valid()) {
       mValue += other.Value();
     } else {
       mValue = 0;
       mValid = false;
     }
   }
   // Is it word-aligned?
   bool IsAligned() const {
     return mValid && (mValue & (sizeof(uintptr_t)-1)) == 0;
   }
   uintptr_t Value() const { return mValue; }
   bool      Valid() const { return mValid; }
 private:
   uintptr_t mValue;
   bool mValid;
 };
 // The registers, with validity tags, that will be unwound.
 struct UnwindRegs {
 #if defined(LUL_ARCH_arm)
   TaggedUWord r7;
   TaggedUWord r11;
   TaggedUWord r12;
   TaggedUWord r13;
   TaggedUWord r14;
   TaggedUWord r15;
 #elif defined(LUL_ARCH_x64) || defined(LUL_ARCH_x86)
   TaggedUWord xbp;
   TaggedUWord xsp;
   TaggedUWord xip;
 #else
 # error "Unknown plat"
 #endif
 };
 // The maximum number of bytes in a stack snapshot.  This can be
 // increased if necessary, but larger values cost performance, since a
 // stack snapshot needs to be copied between sampling and worker
 // threads for each snapshot.  In practice 32k seems to be enough
 // to get good backtraces.
 static const size_t N_STACK_BYTES = 32768;
 // The stack chunk image that will be unwound.
 struct StackImage {
   // [start_avma, +len) specify the address range in the buffer.
   // Obviously we require 0 <= len <= N_STACK_BYTES.
   uintptr_t mStartAvma;
   size_t    mLen;
   uint8_t   mContents[N_STACK_BYTES];
 };
 // The core unwinder library class.  Just one of these is needed, and
 // it can be shared by multiple unwinder threads.
 //
 // Access to the library is mediated by a single reader-writer lock.
 // All attempts to change the library's internal shared state -- that
 // is, loading or unloading unwind info -- are forced single-threaded
 // by causing the called routine to acquire a write-lock.  Unwind
 // requests do not change the library's internal shared state and
 // therefore require only a read-lock.  Hence multiple threads can
 // unwind in parallel.
 //
 // The library needs to maintain state which is private to each
 // unwinder thread -- the CFI (Dwarf Call Frame Information) fast
 // cache.  Hence unwinder threads first need to register with the
 // library, so their identities are known.  Also, for maximum
 // effectiveness of the CFI caching, it is preferable to have a small
 // number of very-busy unwinder threads rather than a large number of
 // mostly-idle unwinder threads.
 //
 // None of the methods may be safely called from within a signal
 // handler, since this risks deadlock.  In particular this means
 // a thread may not unwind itself from within a signal handler
 // frame.  It might be safe to call Unwind() on its own stack
 // from not-inside a signal frame, although even that cannot be
 // guaranteed deadlock free.
 class PriMap;
 class SegArray;
 class CFICache;
 class LUL {
 public:
   // Create; supply a logging sink.  Initialises the rw-lock.
   LUL(void (*aLog)(const char*));
   // Destroy.  This acquires mRWlock for writing.  By doing that, waits
   // for all unwinder threads to finish any Unwind() calls they may be
   // in.  All resources are freed and all registered unwinder threads
   // are deregistered.
   ~LUL();
   // Notify of a new r-x mapping, and load the associated unwind info.
   // The filename is strdup'd and used for debug printing.  If
   // aMappedImage is NULL, this function will mmap/munmap the file
   // itself, so as to be able to read the unwind info.  If
   // aMappedImage is non-NULL then it is assumed to point to a
   // called-supplied and caller-managed mapped image of the file.
   //
   // Acquires mRWlock for writing.  This must be called only after the
   // code area in question really has been mapped.
   void NotifyAfterMap(uintptr_t aRXavma, size_t aSize,
                       const char* aFileName, const void* aMappedImage);
   // In rare cases we know an executable area exists but don't know
   // what the associated file is.  This call notifies LUL of such
   // areas.  This is important for correct functioning of stack
   // scanning and of the x86-{linux,android} special-case
   // __kernel_syscall function handling.  Acquires mRWlock for
   // writing.  This must be called only after the code area in
   // question really has been mapped.
   void NotifyExecutableArea(uintptr_t aRXavma, size_t aSize);
   // Notify that a mapped area has been unmapped; discard any
   // associated unwind info.  Acquires mRWlock for writing.  Note that
   // to avoid segfaulting the stack-scan unwinder, which inspects code
   // areas, this must be called before the code area in question is
   // really unmapped.  Note that, unlike NotifyAfterMap(), this
   // function takes the start and end addresses of the range to be
   // unmapped, rather than a start and a length parameter.  This is so
   // as to make it possible to notify an unmap for the entire address
   // space using a single call.
   void NotifyBeforeUnmap(uintptr_t aAvmaMin, uintptr_t aAvmaMax);
   // Apply NotifyBeforeUnmap to the entire address space.  This causes
   // LUL to discard all unwind and executable-area information for the
   // entire address space.
   void NotifyBeforeUnmapAll() {
     NotifyBeforeUnmap(0, UINTPTR_MAX);
   }
   // Returns the number of mappings currently registered.  Acquires
   // mRWlock for writing.
   size_t CountMappings();
   // Register the calling thread for unwinding.  Acquires mRWlock for
   // writing.
   void RegisterUnwinderThread();
   // Unwind |aStackImg| starting with the context in |aStartRegs|.
   // Write the number of frames recovered in *aFramesUsed.  Put
   // the PC values in aFramePCs[0 .. *aFramesUsed-1] and
   // the SP values in aFrameSPs[0 .. *aFramesUsed-1].
   // |aFramesAvail| is the size of the two output arrays and hence the
   // largest possible value of *aFramesUsed.  PC values are always
   // valid, and the unwind will stop when the PC becomes invalid, but
   // the SP values might be invalid, in which case the value zero will
   // be written in the relevant frameSPs[] slot.
   //
   // Unwinding may optionally use stack scanning.  The maximum number
   // of frames that may be recovered by stack scanning is
   // |aScannedFramesAllowed| and the actual number recovered is
   // written into *aScannedFramesAcquired.  |aScannedFramesAllowed|
   // must be less than or equal to |aFramesAvail|.
   //
   // This function assumes that the SP values increase as it unwinds
   // away from the innermost frame -- that is, that the stack grows
   // down.  It monitors SP values as it unwinds to check they
   // decrease, so as to avoid looping on corrupted stacks.
   //
   // Acquires mRWlock for reading.  Hence multiple threads may unwind
   // at once, but no thread may be unwinding whilst the library loads
   // or discards unwind information.  Returns false if the calling
   // thread is not registered for unwinding.
   //
   // Up to aScannedFramesAllowed stack-scanned frames may be recovered.
   //
   // The calling thread must previously have registered itself via
   // RegisterUnwinderThread.
   void Unwind(/*OUT*/uintptr_t* aFramePCs,
               /*OUT*/uintptr_t* aFrameSPs,
               /*OUT*/size_t* aFramesUsed,
               /*OUT*/size_t* aScannedFramesAcquired,
               size_t aFramesAvail,
               size_t aScannedFramesAllowed,
               UnwindRegs* aStartRegs, StackImage* aStackImg);
   // The logging sink.  Call to send debug strings to the caller-
   // specified destination.
   void (*mLog)(const char*);
 private:
   // Invalidate the caches.  Requires mRWlock to be held for writing;
   // does not acquire it itself.
   void InvalidateCFICaches();
   // The one-and-only lock, a reader-writer lock, for the library.
   LulRWLock* mRWlock;
   // The top level mapping from code address ranges to postprocessed
   // unwind info.  Basically a sorted array of (addr, len, info)
   // records.  Threads wishing to query this field must hold mRWlock
   // for reading.  Threads wishing to modify this field must hold
   // mRWlock for writing.  This field is updated by NotifyAfterMap and
   // NotifyBeforeUnmap.
   PriMap* mPriMap;
   // An auxiliary structure that records which address ranges are
   // mapped r-x, for the benefit of the stack scanner.  Threads
   // wishing to query this field must hold mRWlock for reading.
   // Threads wishing to modify this field must hold mRWlock for
   // writing.
   SegArray* mSegArray;
   // The thread-local data: a mapping from threads to CFI-fast-caches.
   // Threads wishing to query this field must hold mRWlock for
   // reading.  Threads wishing to modify this field must hold mRWlock
   // for writing.
   //
   // The CFICaches themselves are thread-local and can be both read
   // and written when mRWlock is held for reading.  It would probably
   // be faster to use the pthread_{set,get}specific functions, but
   // also more difficult.  This map is queried once per unwind, in
   // order to get hold of the CFI cache for a given thread.
   std::map<pthread_t, CFICache*> mCaches;
 };
 // Run unit tests on an initialised, loaded-up LUL instance, and print
 // summary results on |aLUL|'s logging sink.  Also return the number
 // of tests run in *aNTests and the number that passed in
 // *aNTestsPassed.
 void
 RunLulUnitTests(/*OUT*/int* aNTests, /*OUT*/int*aNTestsPassed, LUL* aLUL);
 } // namespace lul
 #endif // LulMain_h

The Tor Browser / annotate

tools/profiler/LulMain.h@97036ab72558 (annotated)

tools/profiler/LulMain.h