From: Matt Davis Date: Tue, 17 Jul 2018 16:11:54 +0000 (+0000) Subject: [llvm-mca][docs] Revert mca internals docs. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=95e53c288972db4334a324a18272024e4e346fba;p=llvm [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 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@337295 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/CommandGuide/llvm-mca.rst b/docs/CommandGuide/llvm-mca.rst index 41c450240c9..b921f35830b 100644 --- a/docs/CommandGuide/llvm-mca.rst +++ b/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= @@ -200,105 +200,10 @@ 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.). - -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.