[Profiler][Docs] Cleanup Profiler Pinning documentation (#110375)

* [Profiler][Docs] Update remaining instances of BEGIN/END_PIN_PROFILER

* [Profiler][Docs] Update profiler pinning comments

Author: mdh1418

docs/design/coreclr/botr/profilability.md

@@ -31,22 +31,23 @@ ICorProfilerCallback
 
 This interface comprises the callbacks made by the CLR into the profiler to notify the profiler of interesting events.  Each callback is wrapped in a thin method in the EE that handles locating the profiler's implementation of ICorProfilerCallback(2), and calling its corresponding method.
 
-Profilers subscribe to events by specifying the corresponding flag in a call to ICorProfilerInfo::SetEventMask().  The profiling API stores these choices and exposes them to the CLR through specialized inline functions (CORProfiler\*) that mask against the bit corresponding to the flag.   Then, sprinkled throughout the CLR, you'll see code that calls the ICorProfilerCallback wrapper to notify the profiler of events as they happen, but this call is conditional on the flag being set (determined by calling the specialized inline function):
+Profilers subscribe to events by specifying the corresponding flag in a call to ICorProfilerInfo::SetEventMask()/ICorProfilerInfo::SetEventMask2().  The profiling API stores these choices and exposes them to the CLR through specialized inline functions (CORProfiler\*) that mask against the bit corresponding to the flag.   Then, sprinkled throughout the CLR, you'll see code that calls the ICorProfilerCallback wrapper to notify the profiler of events as they happen, but this call is conditional on the flag being set (determined by calling the specialized inline function):
 
     {
-        //check if profiler set flag, pin profiler
-        BEGIN_PIN_PROFILER(CORProfilerTrackModuleLoads());
+        // check if profiler set flag
+        BEGIN_PROFILER_CALLBACK(CORProfilerTrackModuleLoads());
 
-        //call the wrapper around the profiler's callback implementation
-        g_profControlBlock.pProfInterface->ModuleLoadStarted((ModuleID) this);
+        // call the ProfControlBlock wrapper around the profiler's callback implementation
+        // which pins the profiler in DoOneProfilerIteration via EvacuationCounterHolder
+        (&g_profControlBlock)->ModuleLoadStarted((ModuleID) this);
+        // unpins the profiler after completing the callback
 
-        //unpin profiler
-        END_PIN_PROFILER();
+        END_PROFILER_CALLBACK();
     }
 
 To be clear, the code above is what you'll see sprinkled throughout the code base.  The function it calls (in this case ModuleLoadStarted()) is our wrapper around the profiler's callback implementation (in this case ICorProfilerCallback::ModuleLoadStarted()).  All of our wrappers appear in a single file (vm\EEToProfInterfaceImpl.cpp), and the guidance provided in the sections below relate to those wrappers; not to the above sample code that calls the wrappers.
 
-The macro BEGIN\_PIN\_PROFILER evaluates the expression passed as its argument.  If the expression is TRUE, then the profiler is pinned into memory (meaning the profiler will not be able to detach from the process) and the code between the BEGIN\_PIN\_PROFILER and END\_PIN\_PROFILER macros is executed.  If the expression is FALSE, all code between the BEGIN\_PIN\_PROFILER and END\_PIN\_PROFILER macros is skipped.  For more information about the BEGIN\_PIN\_PROFILER and END\_PIN\_PROFILER macros, find their definition in the code base and read the comments there.
+The macro BEGIN_PROFILER_CALLBACK evaluates the expression passed as its argument.  If the expression is TRUE, the code between the BEGIN_PROFILER_CALLBACK and END_PROFILER_CALLBACK macros is executed, and the profiler is pinned into memory (meaning the profiler will not be able to detach from the process) through the ProfControlBlock wrapper.  If the expression is FALSE, all code between the BEGIN_PROFILER_CALLBACK and END_PROFILER_CALLBACK macros is skipped.  For more information about the BEGIN_PROFILER_CALLBACK and END_PROFILER_CALLBACK macros, find their definition in the code base and read the comments there.
 
 Contracts
 ---------

src/coreclr/inc/profilepriv.inl

@@ -2114,7 +2114,7 @@ FORCEINLINE BOOL CORProfilerTrackEventPipe()
 // These macros must be placed around any callbacks to g_profControlBlock by
 // the EE. Example:
 //    {
-//        BEGIN_PROFILER_CALLBACK(CORProfilerTrackAppDomainLoads;
+//        BEGIN_PROFILER_CALLBACK(CORProfilerTrackAppDomainLoads());
 //        g_profControlBlock.AppDomainCreationStarted(MyAppDomainID);
 //        END_PROFILER_CALLBACK();
 //    }
@@ -2129,7 +2129,7 @@ FORCEINLINE BOOL CORProfilerTrackEventPipe()
 // block. Example:
 //
 //    {
-//        BEGIN_PROFILER_CALLBACK(CorProfilerTrackTransitions);
+//        BEGIN_PROFILER_CALLBACK(CorProfilerTrackTransitions());
 //        if (!pNSL->pMD->IsQCall())
 //        {
 //            g_profControlBlock.

src/coreclr/nativeaot/Runtime/eventtrace_gcheap.cpp

@@ -232,13 +232,13 @@ void ETW::GCLog::MovedReference(
 #ifdef PROFILING_SUPPORTED
     // ProfAPI
     {
-        BEGIN_PIN_PROFILER(CORProfilerTrackGC());
+        BEGIN_PROFILER_CALLBACK(CORProfilerTrackGC());
         g_profControlBlock.pProfInterface->MovedReference(pbMemBlockStart,
             pbMemBlockEnd,
             cbRelocDistance,
             &(pCtxForEtwAndProfapi->pctxProfAPI),
             fCompacting);
-        END_PIN_PROFILER();
+        END_PROFILER_CALLBACK();
     }
 #endif // PROFILING_SUPPORTED
 
@@ -358,9 +358,9 @@ void ETW::GCLog::EndMovedReferences(size_t profilingContext,
 #ifdef PROFILING_SUPPORTED
     // ProfAPI
     {
-        BEGIN_PIN_PROFILER(CORProfilerTrackGC());
+        BEGIN_PROFILER_CALLBACK(CORProfilerTrackGC());
         g_profControlBlock.pProfInterface->EndMovedReferences(&(pCtxForEtwAndProfapi->pctxProfAPI));
-        END_PIN_PROFILER();
+        END_PROFILER_CALLBACK();
     }
 #endif //PROFILING_SUPPORTED
 

src/coreclr/vm/profilinghelper.cpp

@@ -53,26 +53,28 @@
 // following format:
 //    {
 //        BEGIN_PROFILER_CALLBACK(CORProfilerTrackAppDomainLoads());
-//        g_profControlBlock.pProfInterface->AppDomainCreationStarted(MyAppDomainID);
+//        // call the ProfControlBlock callback wrapper
+//        (&g_profControlBlock)->AppDomainCreationStarted(MyAppDomainID);
 //        END_PROFILER_CALLBACK();
 //    }
-// The BEGIN / END macros do the following:
-// * Evaluate the expression argument (e.g., CORProfilerTrackAppDomainLoads()). This is a
+// The BEGIN / END macros evaluates the expression argument (CORProfiler*). This is a
 //     "dirty read" as the profiler could be detached at any moment during or after that
 //     evaluation.
-// * If true, push a code:EvacuationCounterHolder on the stack, which increments the
-//     per-thread evacuation counter (not interlocked).
-// * Re-evaluate the expression argument. This time, it's a "clean read" (see below for
-//     why).
-// * If still true, execute the statements inside the BEGIN/END block. Inside that block,
-//     the profiler is guaranteed to remain loaded, because the evacuation counter
-//     remains nonzero (again, see below).
-// * Once the BEGIN/END block is exited, the evacuation counter is decremented, and the
-//     profiler is unpinned and allowed to detach.
+//
+// The ProfControlBlock callback wrappers call DoOneProfilerIteration, doing the following:
+// * Pushes a code:EvacuationCounterHolder on the stack for the ProfilerInfo, which
+//     increments the per-thread evacuation counter (not interlocked).
+// * Checks the profiler status (code:ProfilerStatus) to see if the profiler is active.
+// * Evaluates the ProfControlBlock condition func (e.g. IsProfilerTrackingAppDomainLoads).
+// * If true, invokes the callback func (e.g. AppDomainCreationStartedHelper) which in turn
+//     calls the EEToProfInterfaceImpl implementation where the profiler is guaranteed to
+//     remain loaded, because the evacuation counter remains nonzero (again, see below).
+// * Once the DoOneProfilerIteration block is exited, the evacuation counter is decremented
+//     and the profiler is unpinned and allowed to detach.
 //
 // READER / WRITER COORDINATION
 //
-// The above ensures that a reader never touches g_profControlBlock.pProfInterface and
+// The above ensures that a reader never touches EEToProfInterfaceImpl and
 // all it embodies (including the profiler DLL code and callback implementations) unless
 // the reader was able to increment its thread's evacuation counter AND re-verify that
 // the profiler's status is still active (the status check is included in the macro's