zackcquic commented on a change in pull request #8220: URL: https://github.com/apache/tvm/pull/8220#discussion_r648118036
########## File path: docs/api/python/ir.rst ########## @@ -23,6 +23,14 @@ tvm.ir :autosummary: +tvm.ir.instrument Review comment: Use tvm.instrument ########## File path: docs/dev/pass_infra.rst ########## @@ -526,6 +579,51 @@ decorators and then invoke it. For more examples about how to customize your own optimization pipeline and debug Relay and tir passes, please refer to the `use pass infra`_ tutorial. +Pass Instrument +^^^^^^^^^^^^^^^ + +A customizable framework to instrument passes is provided. ``PassInstrument`` classes can be registered while constructing ``PassContext``. + +.. code:: python + + @tvm._ffi.register_object("transform.PassContext") + class PassContext(tvm.runtime.Object): + def __init__( + self, + opt_level=2, + required_pass=None, + disabled_pass=None, + instruments=None, + config=None, + ): + # ... + +One can implement a ``PassInstrument`` by ``pass_instrument`` decorator(`python/tvm/ir/instrument.py`_) with a class implementing following methods: + +- ``enter_pass_ctx`` + + * This callback is run at the moement of entering ``PassContext``. + +- ``exit_pass_ctx`` + + * This callback is run at the moement of exiting ``PassContext``. + +- ``should_run`` + + * This callback is run before a pass is executed, returning a boolean indicating if the pass should be run. + * If a pass is listed as required, this callback will not be executed for that pass. Review comment: This callback will not be executed for that pass. -> should_run will not have effect and not be executed. ########## 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: Add exception situations. ########## 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: How about remove "For more details, ... " ? ########## 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: Pass instrument framework extended ... instrument instances, Also a decorator :py:func:`tvm.instrument.pass_instrument` ... instrument instances. -- 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: us...@infra.apache.org