Add global alias for DUT parameter

This feature will allow users to parameterize module-level classes and
functions, and arguments to `TestFactory`s.

cocotb/__init__.py

@@ -128,6 +128,16 @@ def _reopen_stream_with_buffering(stream_name):
 _library_coverage = None
 """ used for cocotb library coverage """
 
+top = None  # type: cocotb.handle.SimHandleBase
+"""
+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:`~cocotb.regression.TestFactory`s.
+``None`` if :mod:`cocotb` was not loaded from a simulator.
+"""
+
 
 def fork(coro):
     """ Schedule a coroutine to be run concurrently. See :ref:`coroutines` for details on its use. """
@@ -238,11 +248,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/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 @@
+Made the handle to :envvar:`TOPLEVEL`, typically seen as the first argument to a cocotb test function, available globally as :data:`cocotb.top`.