[llvm] r337295 - [llvm-mca][docs] Revert mca internals docs.

Tue Jul 17 09:11:54 PDT 2018

Author: mattd
Date: Tue Jul 17 09:11:54 2018
New Revision: 337295

URL: http://llvm.org/viewvc/llvm-project?rev=337295&view=rev
Log:
[llvm-mca][docs] Revert mca internals docs.

We're going to work on this in a separate review focusing more on documenting
the View and probably removing some of the less-interesting/less-useful pieces.

This reverts r337219,337225


Modified:
    llvm/trunk/docs/CommandGuide/llvm-mca.rst

Modified: llvm/trunk/docs/CommandGuide/llvm-mca.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CommandGuide/llvm-mca.rst?rev=337295&r1=337294&r2=337295&view=diff
==============================================================================

--- llvm/trunk/docs/CommandGuide/llvm-mca.rst (original)
+++ llvm/trunk/docs/CommandGuide/llvm-mca.rst Tue Jul 17 09:11:54 2018
@@ -43,7 +43,7 @@ instruction in the input file.  Every re
 final performance report is the union of all the reports generated for every
 code region.
 
-Inline assembly directives may be used from source code to annotate the
+Inline assembly directives may be used from source code to annotate the 
 assembly text:
 
 .. code-block:: c++
@@ -132,7 +132,7 @@ option specifies "``-``", then the outpu
   Specify the size of the load queue in the load/store unit emulated by the tool.
   By default, the tool assumes an unbound number of entries in the load queue.
   A value of zero for this flag is ignored, and the default load queue size is
-  used instead.
+  used instead. 
 
 .. option:: -squeue=<store queue size>
 
@@ -200,105 +200,10 @@ option specifies "``-``", then the outpu
   the theoretical uniform distribution of resource pressure for every
   instruction in sequence.
 
+
 EXIT STATUS
 -----------
 
 :program:`llvm-mca` returns 0 on success. Otherwise, an error message is printed
 to standard error, and the tool returns 1.
 
-INTERNALS
----------
-Why MCA?  For many analysis scenarios :program:`llvm-mca` (MCA) should work
-just fine out of the box; however, the tools MCA provides allows for the
-curious to create their own pipelines, and explore the finer details of
-instruction processing.
-
-MCA is designed to be a flexible framework allowing users to easily create
-custom instruction pipeline simulations.  The following section describes the
-primary components necessary for creating a pipeline, namely the classes
-``Pipeline``, ``Stage``, ``HardwareUnit``, and ``View``.
-
-In most cases, creating a custom pipeline is not necessary, and using the
-default ``mca::Context::createDefaultPipeline`` will work just fine.  Instead,
-a user will probably find it easier, and faster, to implement a custom
-``View``, allowing them to specifically handle the processing and presenting of
-data.  Views are discussed towards the end of this document, as it can be
-helpful to first understand how the rest of MCA is structured and where the
-views sit in the bigger picture.
-
-Primary Components of MCA
-^^^^^^^^^^^^^^^^^^^^^^^^^
-A pipeline is a collection of stages.  Stages are the real workhorse of
-MCA, since all of the instruction processing occurs within them.  A stage
-operates on instructions (``InstRef``) and utilizes the simulated hardware
-units (``HardwareUnit``).  We draw a strong distinction between a ``Stage`` and
-a ``HardwareUnit``.  Stages make use of HardwareUnits to accomplish their
-primary action, which is defined in ``mca::Stage::execute``.  HardwareUnits
-maintain state and act as a mechanism for inter-stage communication.  For
-instance, both ``DispatchStage`` and ``RetireStage`` stages make use of the
-simulated ``RegisterFile`` hardware unit for updating the state of particular
-registers.
-
-The pipeline's role is to simply execute the stages in order.  During
-execution, a stage can return ``false`` from ``mca::Stage:execute``, indicating
-to the pipeline that no more executions are to continue for the current cycle.
-This mechanism allows for a stage to short-circuit the rest of execution for
-any cycle.
-
-Views
-^^^^^
-Of course simulating a pipeline is great, but it's not very useful if a user
-cannot extract data from it!  This is where views come into play. The goal of a
-``View`` is to collect events from the pipeline's stages.  The view can
-analyze and present this collected information in a more comprehensible manner.
-
-If the default views provided by MCA are not sufficient, then a user might
-consider implementing a custom data collection and presentation mechanism (a
-``View``).  Views receive callback notifications from the pipeline simulation,
-specifically from the stages.  To accomplish this communication, stages contain
-a list of listeners.  A view is a listener (``HWEventListener``) and can be
-added to a single stage's list of listeners, or to all stages lists, by
-expressing interest to be notified when particular hardware events occur (e.g.,
-a hardware stall).
-
-Notifications are generated within the stages.  When an event occurs, the stage
-will iterate through its list of listeners (presumably a View) and will send
-an event object describing the situation to the Listener.
-
-What Data does a View Collect?
-""""""""""""""""""""""""""""""
-The two primary event types sent to views are instruction events
-(``HWInstructionEvent``) and stall events (``HWStallEvent``).  The former
-describes the state of an instruction (e.g., Ready, Dispatched, Executed,
-etc.).  The latter describes a stall hazard (e.g., load stall, store stall,
-scheduler stall, etc.).
-
-In addition to the instruction and stall events.  A listener can also
-subscribe to cycle events (``onCycleStart``, ``onCycleEnd``).  These events
-occur before and after a simulated clock cycle is executed, respectively.
-
-Listeners can also be notified of various resource states within the stages
-of a pipeline, such as resource availability, reservation, and reclaim:
-(``onResourceAvailability``, ``onReservedBuffers``, ``onReleasedBuffers``).
-
-Creating a Custom View
-""""""""""""""""""""""
-To create a  custom view, the user must first inherit from the ``View`` class
-and then decide which events are of interest.  The ``HWEventListener`` class
-declares the callback functions for the particular event types.  A custom view
-should define the callbacks for the events of interest.
-
-Next, the view should define a ``mca::View::printView`` method.  This is called
-once the pipeline has completed executing all of the desired cycles.  A
-user can choose to perform analysis in the aforementioned routine, or do the
-analysis incrementally as the event callbacks are triggered.  All presentation
-of the data should be performed in ``printView``.
-
-With a view created, the next step is to tell the pipeline's stages about it.
-The simplest way to accomplish this is to create a ``PipelinePrinter`` object
-and call ``mca::PipelinePrinter::addView``.  We have not discussed the
-PipelinePrinter before, but it is simply a helper class containing a collection
-of views and a pointer to the pipeline instance.  When ``addView`` is called,
-the printer will take the liberty of registering the view as a listener to all
-of the stages in the pipeline.  The printer provides a ``printReport`` routine
-that iterates across all views and calls each view's ``printView`` method.


