[llvm-mca][docs] Initial description of mca internals. NFC

This patch introduces a brief description of the components of MCA.  The main
focus is on Views.   This is a work in progress, and more descriptions will be
introduced later.  I want to flesh-out the Views section more and provide a
detailed description of eventing in MCA.  Eventually a brief code example of a
View should accompany the description.

Also, we should consider moving the MCA internals guide elsewhere at some point.

llvm-svn: 337219

docs/CommandGuide/llvm-mca.rst

@@ -43,7 +43,7 @@ instruction in the input file.  Every region is analyzed in isolation, and the
 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 output will also be sent to standard output.
   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,10 +200,97 @@ option specifies "``-``", then the output will also be sent to standard output.
   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.).
+
+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.