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

Tue Jul 17 03:53:51 PDT 2018

Hi Matt.

Next time, could you please create a code review for changes to the
documentation?
I think the priority should be on decribing what the tool does, and what
information is provided by each view. Internal details on the
implementation are not very useful at this stage, and - as you wrote - that
documentation should probably live in a separate document.
That being said, thanks for contributing this documentation change.

On Mon, Jul 16, 2018 at 10:42 PM, Matt Davis via llvm-commits <
llvm-commits at lists.llvm.org> wrote:

> Author: mattd
> Date: Mon Jul 16 14:42:58 2018
> New Revision: 337219
>
> URL: http://llvm.org/viewvc/llvm-project?rev=337219&view=rev
> Log:
> [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.
>
>
> 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=337219&r1=337218&r2=337219&view=diff
> ============================================================
> ==================
> --- llvm/trunk/docs/CommandGuide/llvm-mca.rst (original)
> +++ llvm/trunk/docs/CommandGuide/llvm-mca.rst Mon Jul 16 14:42:58 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,10 +200,97 @@ 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.).
> +
> +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.
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180717/a71a7892/attachment.html>