Add global alias for DUT parameter

cocotb/__init__.py

@@ -129,6 +129,16 @@ def _reopen_stream_with_buffering(stream_name):
 _library_coverage = None
 """ used for cocotb library coverage """
 
+top = None  # type: cocotb.handle.SimHandleBase
+r"""
+A handle to the :envvar:`TOPLEVEL` entity/module.
+
+This is equivalent to the :term:`DUT` parameter given to cocotb tests, so it can be used wherever that variable can be used.
+It is particularly useful for extracting information about the :term:`DUT` in module-level class and function definitions;
+and in parameters to :class:`.TestFactory`\ s.
+``None`` if :mod:`cocotb` was not loaded from a simulator.
+"""
+
 
 def fork(coro: Union[RunningTask, Coroutine]) -> RunningTask:
     """ Schedule a coroutine to be run concurrently. See :ref:`coroutines` for details on its use. """
@@ -239,11 +249,12 @@ def _initialise_testbench(argv_):
     if not handle:
         raise RuntimeError("Can not find root handle ({})".format(root_name))
 
-    dut = cocotb.handle.SimHandle(handle)
+    global top
+    top = cocotb.handle.SimHandle(handle)
 
     # start Regression Manager
     global regression_manager
-    regression_manager = RegressionManager.from_discovery(dut)
+    regression_manager = RegressionManager.from_discovery(top)
     regression_manager.execute()
 
     _rlock.release()

documentation/source/building.rst

@@ -45,6 +45,9 @@ Cocotb
     Use this to indicate the instance in the hierarchy to use as the :term:`DUT`.
     If this isn't defined then the first root instance is used.
 
+    The DUT is available in cocotb tests as a Python object at :data:`cocotb.top`;
+    and is also passed to all cocotb tests as the :ref:`first and only parameter <quickstart_creating_a_test>`.
+
 .. envvar:: RANDOM_SEED
 
     Seed the Python random module to recreate a previous test stimulus.

documentation/source/library_reference.rst

@@ -369,6 +369,8 @@ Other Runtime Information
 
 .. autodata:: cocotb.LANGUAGE
 
+.. autodata:: cocotb.top
+
 
 Signal Tracer for WaveDrom
 --------------------------

documentation/source/newsfragments/2134.feature.rst

@@ -0,0 +1 @@
+The handle to :envvar:`TOPLEVEL`, typically seen as the first argument to a cocotb test function, is now available globally as :data:`cocotb.top`.

documentation/source/quickstart.rst

@@ -78,6 +78,8 @@ Python test script to load.
 We would then create a file called ``test_my_design.py`` containing our tests.
 
 
+.. _quickstart_creating_a_test:
+
 Creating a test
 ---------------