areusch commented on a change in pull request #8220:
URL: https://github.com/apache/tvm/pull/8220#discussion_r659020139
##########
File path: docs/dev/pass_infra.rst
##########
@@ -389,6 +396,136 @@ To allow other C++ modules to apply this pass, we declare
a free function in
TVM_DLL Pass FoldConstant();
+.. _pass_instrument_cpp_backend:
+
+Pass Instrument
+^^^^^^^^^^^^^^^
+
+Currently we introduce four instrument points in the life-cycle of
``PassContext``.
+
+.. code:: c++
+
+ TVM_DLL void InstrumentEnterPassContext();
+ TVM_DLL void InstrumentExitPassContext();
+ TVM_DLL bool InstrumentBeforePass(const IRModule& mod, const PassInfo&
info) const;
+ TVM_DLL void InstrumentAfterPass(const IRModule& mod, const PassInfo&
info) const;
+
+``InstrumentEnterPassContext`` is called immediately when entering the scope
+of the ``PassContext`` instance.
+
+``InstrumentExitPassContext`` is called when leaving the scope of
``PassContext``,
+or exceptions occur during the execution of passes.
+This method is also called when instruments is being overriden by
``override_instruments`` in :py:class:`tvm.transform.PassContext`.
+See :ref:`pass_instrument_overriden`.
+
+``InstrumentBeforePass`` is called before execution.
+``InstrumentAfterPass`` is called after executioon if the pass should be run.
The behavior is like:
+
+.. code:: c++
+
+ if (pass_ctx.InstrumentBeforePass(ir_module, pass_info)) {
+ new_ir_module = run_pass(ir_module, pass_ctx);
+ pass_ctx.InstrumentAfterPass(new_ir_module, pass_info);
+ return new_ir_module;
+ }
+
+The ``PassInstrument`` interface allow you to run arbitrary code inside above
four methods.
+Multiple ``PassInstrument`` instances can be registed into a single
+``PassContext``. ``PassInstrument`` instances are called sequentially in the
order of
+``instruments`` argument passed to ``PassContext``.
+
+``PassInstrument`` provides following interfaces:
+
+.. code:: c++
+
+ namespace instrument {
+
+ class PassInstrumentNode : public Object {
+ public:
+ String name;
+ virtual void EnterPassContext() const = 0;
+ virtual void ExitPassContext() const = 0;
+ virtual bool ShouldRun(const IRModule& mod, const transform::PassInfo&
info) const = 0;
+ virtual void RunBeforePass(const IRModule& mod, const
transform::PassInfo& info) const = 0;
+ virtual void RunAfterPass(const IRModule& mod, const
transform::PassInfo& info) const = 0;
+ /* Other fields are omitted. */
+ };
+
+ class PassInstrument : public ObjectRef {
+ public:
+ TVM_DEFINE_OBJECT_REF_METHODS(PassInstrument, ObjectRef,
PassInstrumentNode);
+ };
+
+ } // namespace instrument
+
+Python frontend are provided to implement ``PassInstrument`` quickly. See
:ref:`pass_instrument_py_frontend`.
+
+Within a ``PassContext``, the call sequence of a ``PassInstrument`` instance
is like:
+
+::
+
+ with PassContext(instruments=[pi]) # pi = a PassInstrument implementation.
+ pi.EnterPassContext()
+
+ if pi.ShouldRun(Pass1):
+ pi.RunBeforePass()
+ Pass1()
+ pi.RunAfterPass()
+
+ if pi.ShouldRun(Pass2):
+ pi.RunBeforePass()
+ Pass2()
+ pi.RunAfterPass()
+
+ pi.ExitPassContext()
+
+Here is a brief introduction of relations between ``PassInstrument`` interfaces
+and ``PassContext`` methods. See (`src/ir/transform.cc`_) for more details.
+
+- ``InstrumentEnterPassContext``
+
+ * ``EnterPassContext()`` is executed in the order of ``instruments`` passed
to the ``PassContext``.
+ * When an exception raises, ``PassContext`` disable the pass instrumentation
+ by clearing all registered ``PassInstrument`` instances.
+ * Then ``PassContext`` execute ``ExitPassContext()`` method of each
``PassInstrument``
+ instances which successfully finished ``EnterPassContext()``
+ * For example, if ``PassInstrument`` A, B, and C are registered to a
``PassContext``
+ and A finished ``EnterPassContext()`` while B throws an exception, then C
+ is never executed; ``ExitPassContext()`` of A is executed.
+
+- ``InstrumentExitPassContext``
+
+ * ``ExitPassContext()`` of each ``PassInstrument`` instances are executed in
+ the order of ``instruments`` passed to the ``PassContext``.
+ * While an exception occurs, ``instruments`` is cleared.
+ * ``PassInstrument`` Instances registered after the one throwing exceptions
do not execute ``ExitPassContext``.
+
+- ``InstrumentBeforePass``
+
+ * ``ShouldRun`` is executed if the pass is not listed as a required pass.
+ * ``RunBeforePass`` is executed in the order of ``instruments`` if the pass
is not blocked by ``ShouldRun``.
+ * Note that ``InstrumentBeforePass`` returns a boolean indicating whether or
not the pass should be run.
+ * When an exception occur, it is thrown immediately.
+ We rely on Python Context Manager to exit ``PassContext`` safely
+ (meaning ``ExitPassContext`` of each instruments will be run. For C++,
please refer to `include/tvm/support/with.h`_.)
+
+- ``InstrumentAfterPass``
+
+ * ``RunAfterPass`` is executed in the order of ``instruments`` passed to the
``PassContext``.
+ * When an exception occur, it is thrown immediately.
+ We rely on Python Context Manager or ``With``
class(`include/tvm/support/with.h`_) to exit ``PassContext`` safely
+
+Built-in Instrument
+^^^^^^^^^^^^^^^^^^^
+
+There are several built-in instruments. Those marked with *TODO* are not
implemented yet.
+
+PassTimmingInstrument (see `src/ir/instrument.cc`_)
Review comment:
nit: Timing
##########
File path: docs/dev/pass_infra.rst
##########
@@ -389,6 +396,103 @@ To allow other C++ modules to apply this pass, we declare
a free function in
TVM_DLL Pass FoldConstant();
+.. _pass_instrument_section_tag:
+
+Pass Instrument
Review comment:
ah i see. what do you think about documenting the PassInstrument first,
since that's the developer-facing thing? TVM calls `InstrumentEnterPassContext`.
i think explaining the C++ thing first and then the Python thing is
workable. i agree it's a bit tricky to work around the split. I don't think the
Python docs need to be as extensive since they mostly wrap the C++ stuff
##########
File path: docs/dev/pass_infra.rst
##########
@@ -389,6 +396,136 @@ To allow other C++ modules to apply this pass, we declare
a free function in
TVM_DLL Pass FoldConstant();
+.. _pass_instrument_cpp_backend:
+
+Pass Instrument
+^^^^^^^^^^^^^^^
+
+Currently we introduce four instrument points in the life-cycle of
``PassContext``.
+
+.. code:: c++
+
+ TVM_DLL void InstrumentEnterPassContext();
+ TVM_DLL void InstrumentExitPassContext();
+ TVM_DLL bool InstrumentBeforePass(const IRModule& mod, const PassInfo&
info) const;
+ TVM_DLL void InstrumentAfterPass(const IRModule& mod, const PassInfo&
info) const;
+
+``InstrumentEnterPassContext`` is called immediately when entering the scope
+of the ``PassContext`` instance.
+
+``InstrumentExitPassContext`` is called when leaving the scope of
``PassContext``,
+or exceptions occur during the execution of passes.
+This method is also called when instruments is being overriden by
``override_instruments`` in :py:class:`tvm.transform.PassContext`.
+See :ref:`pass_instrument_overriden`.
+
+``InstrumentBeforePass`` is called before execution.
+``InstrumentAfterPass`` is called after executioon if the pass should be run.
The behavior is like:
Review comment:
nit: execution
##########
File path: docs/dev/pass_infra.rst
##########
@@ -389,6 +396,136 @@ To allow other C++ modules to apply this pass, we declare
a free function in
TVM_DLL Pass FoldConstant();
+.. _pass_instrument_cpp_backend:
+
+Pass Instrument
+^^^^^^^^^^^^^^^
+
+Currently we introduce four instrument points in the life-cycle of
``PassContext``.
+
+.. code:: c++
+
+ TVM_DLL void InstrumentEnterPassContext();
+ TVM_DLL void InstrumentExitPassContext();
+ TVM_DLL bool InstrumentBeforePass(const IRModule& mod, const PassInfo&
info) const;
+ TVM_DLL void InstrumentAfterPass(const IRModule& mod, const PassInfo&
info) const;
+
+``InstrumentEnterPassContext`` is called immediately when entering the scope
+of the ``PassContext`` instance.
+
+``InstrumentExitPassContext`` is called when leaving the scope of
``PassContext``,
+or exceptions occur during the execution of passes.
+This method is also called when instruments is being overriden by
``override_instruments`` in :py:class:`tvm.transform.PassContext`.
+See :ref:`pass_instrument_overriden`.
+
+``InstrumentBeforePass`` is called before execution.
+``InstrumentAfterPass`` is called after executioon if the pass should be run.
The behavior is like:
+
+.. code:: c++
+
+ if (pass_ctx.InstrumentBeforePass(ir_module, pass_info)) {
+ new_ir_module = run_pass(ir_module, pass_ctx);
+ pass_ctx.InstrumentAfterPass(new_ir_module, pass_info);
+ return new_ir_module;
+ }
+
+The ``PassInstrument`` interface allow you to run arbitrary code inside above
four methods.
+Multiple ``PassInstrument`` instances can be registed into a single
+``PassContext``. ``PassInstrument`` instances are called sequentially in the
order of
+``instruments`` argument passed to ``PassContext``.
+
+``PassInstrument`` provides following interfaces:
+
+.. code:: c++
+
+ namespace instrument {
+
+ class PassInstrumentNode : public Object {
+ public:
+ String name;
+ virtual void EnterPassContext() const = 0;
+ virtual void ExitPassContext() const = 0;
+ virtual bool ShouldRun(const IRModule& mod, const transform::PassInfo&
info) const = 0;
+ virtual void RunBeforePass(const IRModule& mod, const
transform::PassInfo& info) const = 0;
+ virtual void RunAfterPass(const IRModule& mod, const
transform::PassInfo& info) const = 0;
+ /* Other fields are omitted. */
+ };
+
+ class PassInstrument : public ObjectRef {
+ public:
+ TVM_DEFINE_OBJECT_REF_METHODS(PassInstrument, ObjectRef,
PassInstrumentNode);
+ };
+
+ } // namespace instrument
+
+Python frontend are provided to implement ``PassInstrument`` quickly. See
:ref:`pass_instrument_py_frontend`.
+
+Within a ``PassContext``, the call sequence of a ``PassInstrument`` instance
is like:
+
+::
+
+ with PassContext(instruments=[pi]) # pi = a PassInstrument implementation.
+ pi.EnterPassContext()
+
+ if pi.ShouldRun(Pass1):
+ pi.RunBeforePass()
+ Pass1()
+ pi.RunAfterPass()
+
+ if pi.ShouldRun(Pass2):
+ pi.RunBeforePass()
+ Pass2()
+ pi.RunAfterPass()
+
+ pi.ExitPassContext()
+
+Here is a brief introduction of relations between ``PassInstrument`` interfaces
+and ``PassContext`` methods. See (`src/ir/transform.cc`_) for more details.
+
+- ``InstrumentEnterPassContext``
+
+ * ``EnterPassContext()`` is executed in the order of ``instruments`` passed
to the ``PassContext``.
+ * When an exception raises, ``PassContext`` disable the pass instrumentation
+ by clearing all registered ``PassInstrument`` instances.
+ * Then ``PassContext`` execute ``ExitPassContext()`` method of each
``PassInstrument``
+ instances which successfully finished ``EnterPassContext()``
+ * For example, if ``PassInstrument`` A, B, and C are registered to a
``PassContext``
+ and A finished ``EnterPassContext()`` while B throws an exception, then C
+ is never executed; ``ExitPassContext()`` of A is executed.
+
+- ``InstrumentExitPassContext``
+
+ * ``ExitPassContext()`` of each ``PassInstrument`` instances are executed in
+ the order of ``instruments`` passed to the ``PassContext``.
+ * While an exception occurs, ``instruments`` is cleared.
+ * ``PassInstrument`` Instances registered after the one throwing exceptions
do not execute ``ExitPassContext``.
+
+- ``InstrumentBeforePass``
+
+ * ``ShouldRun`` is executed if the pass is not listed as a required pass.
+ * ``RunBeforePass`` is executed in the order of ``instruments`` if the pass
is not blocked by ``ShouldRun``.
+ * Note that ``InstrumentBeforePass`` returns a boolean indicating whether or
not the pass should be run.
+ * When an exception occur, it is thrown immediately.
+ We rely on Python Context Manager to exit ``PassContext`` safely
+ (meaning ``ExitPassContext`` of each instruments will be run. For C++,
please refer to `include/tvm/support/with.h`_.)
+
+- ``InstrumentAfterPass``
+
+ * ``RunAfterPass`` is executed in the order of ``instruments`` passed to the
``PassContext``.
+ * When an exception occur, it is thrown immediately.
+ We rely on Python Context Manager or ``With``
class(`include/tvm/support/with.h`_) to exit ``PassContext`` safely
+
+Built-in Instrument
+^^^^^^^^^^^^^^^^^^^
+
+There are several built-in instruments. Those marked with *TODO* are not
implemented yet.
+
+PassTimmingInstrument (see `src/ir/instrument.cc`_)
+
+PrintBefore(TODO)
Review comment:
could you give a short explanation what these are?
##########
File path: docs/dev/pass_infra.rst
##########
@@ -389,6 +396,136 @@ To allow other C++ modules to apply this pass, we declare
a free function in
TVM_DLL Pass FoldConstant();
+.. _pass_instrument_cpp_backend:
+
+Pass Instrument
+^^^^^^^^^^^^^^^
+
+Currently we introduce four instrument points in the life-cycle of
``PassContext``.
Review comment:
maybe could you add a short sentence explaining what a "Pass Instrument"
is? e.g. what does it mean to "instrument" the pass manager?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
