tests: Add VM_PREFIX_INCLUDE_DPI (#8386)

docs/guide/connecting.rst

@@ -40,6 +40,30 @@ model:
   internals, including ``/* verilator public_flat */`` items.
 
 
+.. _model header include macros:
+
+Model Header Include Macros
+---------------------------
+
+Code compiled with the generated :file:`{prefix}.mk`, or with the CMake
+``verilate()`` command, gets preprocessor macros that expand to the model
+header includes, so user C++ need not hard-code the :vlopt:`--prefix`:
+
+.. code-block:: C++
+
+   #include VM_PREFIX_INCLUDE      // e.g. <Vtop.h>
+   #include VM_PREFIX_INCLUDE_DPI  // e.g. <Vtop__Dpi.h>
+
+``VM_PREFIX_INCLUDE_DPI`` is defined only when Verilator generates the
+:file:`{prefix}__Dpi.h` header, which is the case for designs with DPI and
+also for public-signal access such as :vlopt:`--public-flat-rw`. Using it
+otherwise is a compile-time error.
+
+A target built from several models defines each macro once, naming the
+first model, as one target has one set of preprocessor definitions. Code
+that must reach a second model's header names it directly.
+
+
 .. _porting from pre 4.210:
 
 Model interface changes in version 4.210
@@ -207,6 +231,9 @@ command line, or the link), you'd then:
    #include "Vour__Dpi.h"
    int add(int a, int b) { return a+b; }
 
+Rather than hard-coding the prefix, ``#include VM_PREFIX_INCLUDE_DPI`` may
+be used instead; see :ref:`Model Header Include Macros`.
+
 
 DPI System Task/Functions
 -------------------------