zackcquic commented on a change in pull request #8220:
URL: https://github.com/apache/tvm/pull/8220#discussion_r650028213
##########
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
+~~~~~~~~~~~~~~~
+
+``PassInstrument`` provides callbacks run when entering/exiting
``PassContext`` and before/after executing passes.
+Multiple ``PassInstrument`` instances can be registed into a single
``PassContext``.
+Instrument instances are called sequentially in the order of ``instruments``
argument passed to ``PassContext``.
+
+.. 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 interfaces are provided to implement ``PassInstrument`` quickly.
+
+Following four methods are invoked in the life-cycle of ``PassContext``.
Review comment:
Currently we introduces four instrument point in the life-cycle of
``PassContext``. (introduce in python frontend maybe better)
Include the text graph in
https://github.com/apache/tvm/blob/d69011dea6a09960b38d36f679888a6e29c24240/include/tvm/ir/instrument.h#L52
maybe helpful to understand quickly (move this to python frontend, too?)
##########
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
+~~~~~~~~~~~~~~~
+
+``PassInstrument`` provides callbacks run when entering/exiting
``PassContext`` and before/after executing passes.
+Multiple ``PassInstrument`` instances can be registed into a single
``PassContext``.
+Instrument instances are called sequentially in the order of ``instruments``
argument passed to ``PassContext``.
+
+.. 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 interfaces are provided to implement ``PassInstrument`` quickly.
+
+Following four methods are invoked 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 the scope
+of the ``PassContext`` instance is entered.
+
+``InstrumentExitPassContext`` is called when the scope of ``PassContextNode``
+is being leaved, 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`.
+
+``InstrumentBeforePass`` is called before pass-execution.
+``InstrumentAfterPass`` is called after pass-executioon if the pass should be
run. The behavir 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;
+ }
+
+Here is a brief introduction of each 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.
+ * That means, instances registered after the one throwing exceptions do not
execute ``ExitPassContext``.
+
+- ``InstrumentBeforePass``
+
+ * ``ShouldRun`` callbakc is executed if the pass is not listed as a required
pass.
+ If the pass is a required pass, ``ShouldRun`` will not be executed for
that pass.
Review comment:
Seems this sentence is same with above. Maybe able to remove.
##########
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
+~~~~~~~~~~~~~~~
+
+``PassInstrument`` provides callbacks run when entering/exiting
``PassContext`` and before/after executing passes.
+Multiple ``PassInstrument`` instances can be registed into a single
``PassContext``.
+Instrument instances are called sequentially in the order of ``instruments``
argument passed to ``PassContext``.
+
+.. 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 interfaces are provided to implement ``PassInstrument`` quickly.
+
+Following four methods are invoked 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 the scope
+of the ``PassContext`` instance is entered.
+
+``InstrumentExitPassContext`` is called when the scope of ``PassContextNode``
+is being leaved, 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`.
+
+``InstrumentBeforePass`` is called before pass-execution.
+``InstrumentAfterPass`` is called after pass-executioon if the pass should be
run. The behavir 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;
+ }
+
+Here is a brief introduction of each 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.
+ * That means, instances registered after the one throwing exceptions do not
execute ``ExitPassContext``.
+
+- ``InstrumentBeforePass``
+
+ * ``ShouldRun`` callbakc is executed if the pass is not listed as a required
pass.
Review comment:
callback
##########
File path: docs/dev/pass_infra.rst
##########
@@ -389,6 +397,51 @@ To allow other C++ modules to apply this pass, we declare
a free function in
TVM_DLL Pass FoldConstant();
+Pass Instrument
+~~~~~~~~~~~~~~~
+
+To instrument passes, four methods are introduced to ``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;
+
+The first two methods are called respectively in entering/exiting context
scope. The latter two are called while passes is being
applied(`src/ir/transform.cc`_).
+
+Note that ``InstrumentBeforePass()`` return a boolean indicating this pass
should
+be run or not.
+
+``PassInstrument`` provides callbacks run by these methods. Multiple
+``PassInstrument`` instances can be registed into a single ``PassContext``.
+They are called sequentially in the order of ``instruments`` member.
+
Review comment:
I think it maybe better to move python frontend ahead, use it to
introduce what is a pass instrument and instrument points, then goes to the
discussion in PassContext::Instrument*
##########
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
+~~~~~~~~~~~~~~~
+
+``PassInstrument`` provides callbacks run when entering/exiting
``PassContext`` and before/after executing passes.
+Multiple ``PassInstrument`` instances can be registed into a single
``PassContext``.
+Instrument instances are called sequentially in the order of ``instruments``
argument passed to ``PassContext``.
+
+.. 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 interfaces are provided to implement ``PassInstrument`` quickly.
+
+Following four methods are invoked 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 the scope
+of the ``PassContext`` instance is entered.
Review comment:
when entering the scope of ``PassContext`` instance.
##########
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
+~~~~~~~~~~~~~~~
+
+``PassInstrument`` provides callbacks run when entering/exiting
``PassContext`` and before/after executing passes.
+Multiple ``PassInstrument`` instances can be registed into a single
``PassContext``.
+Instrument instances are called sequentially in the order of ``instruments``
argument passed to ``PassContext``.
+
+.. 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 interfaces are provided to implement ``PassInstrument`` quickly.
+
+Following four methods are invoked 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 the scope
+of the ``PassContext`` instance is entered.
+
+``InstrumentExitPassContext`` is called when the scope of ``PassContextNode``
Review comment:
when leaving the scope of ``PassContext`` instance
##########
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
+~~~~~~~~~~~~~~~
+
+``PassInstrument`` provides callbacks run when entering/exiting
``PassContext`` and before/after executing passes.
Review comment:
provide callbacks to run
##########
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
+~~~~~~~~~~~~~~~
+
+``PassInstrument`` provides callbacks run when entering/exiting
``PassContext`` and before/after executing passes.
+Multiple ``PassInstrument`` instances can be registed into a single
``PassContext``.
+Instrument instances are called sequentially in the order of ``instruments``
argument passed to ``PassContext``.
+
+.. 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 interfaces are provided to implement ``PassInstrument`` quickly.
+
+Following four methods are invoked 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 the scope
+of the ``PassContext`` instance is entered.
+
+``InstrumentExitPassContext`` is called when the scope of ``PassContextNode``
+is being leaved, 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`.
Review comment:
I think ``override_instruments`` should be placed in another little
section to describe along with the concept of global PassContext
##########
File path: tutorials/dev/use_pass_instrument.py
##########
@@ -0,0 +1,206 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+# pylint: disable=line-too-long
+"""
+.. _tutorial-use-pass-instrument:
+
+How to Use TVM Pass Instrument
+==============================
+**Author**: `Chi-Wei Wang <https://github.com/chiwwang>`_
+
+As more and more passes are implemented, it becomes interesting to instrument
+passes execution, analyze per-pass effects and observe various events.
+We have extended :py:class:`tvm.transform.PassContext` to accept a list of
+instrument classes. Also a decorator
:py:func:`tvm.ir.instrument.pass_instrument` is provided to easily implement
instrument classes.
Review comment:
yes, you are right.
So it should be,
Pass instrument framework extended ... instrument **instances**, Also a
decorator :py:func:tvm.instrument.pass_instrument ... instrument **classes**.
Sorry for miss-copied the second one.
##########
File path: tutorials/dev/use_pass_instrument.py
##########
@@ -0,0 +1,206 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+# pylint: disable=line-too-long
+"""
+.. _tutorial-use-pass-instrument:
+
+How to Use TVM Pass Instrument
+==============================
+**Author**: `Chi-Wei Wang <https://github.com/chiwwang>`_
+
+As more and more passes are implemented, it becomes interesting to instrument
+passes execution, analyze per-pass effects and observe various events.
+We have extended :py:class:`tvm.transform.PassContext` to accept a list of
+instrument classes. Also a decorator
:py:func:`tvm.ir.instrument.pass_instrument` is provided to easily implement
instrument classes.
+
+This tutorial demostrates how developers can use ``PassContext`` to instrument
+passes. For more details, please refer to the :ref:`pass-infra`
Review comment:
Seems no change.
--
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.
For queries about this service, please contact Infrastructure at:
[email protected]
