Index: docs/CommandGuide/llvm-mca.rst =================================================================== --- docs/CommandGuide/llvm-mca.rst +++ docs/CommandGuide/llvm-mca.rst @@ -43,7 +43,7 @@ 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 @@ 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= @@ -207,3 +207,99 @@ :program:`llvm-mca` returns 0 on success. Otherwise, an error message is printed to standard error, and the tool returns 1. +INTERNALS +--------- +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.