From aa342a053ace7d4ce6abf0a91384af82e3ab0d5f Mon Sep 17 00:00:00 2001
From: Nick Gasson <nick@nickg.me.uk>
Date: Sun, 7 Apr 2024 09:29:08 +0100
Subject: [PATCH] Update manual for VHPI subprograms

---
 nvc.1 | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/nvc.1 b/nvc.1
index dff95899..43f140be 100644
--- a/nvc.1
+++ b/nvc.1
@@ -1058,10 +1058,45 @@ void (*vhpi_startup_routines[])() = {
 .Ed
 .Pp
 Functions defined in VHPI plugin libraries may be called from VHDL using
-the VHPIDIRECT protocol.  The VHDL function should be declared with the
+either the standard VHPI protocol or a simplified protocol similar to
+.Xr ghdl 1
+.
+.Pp
+To use the standard VHPI protocol the VHDL function should be declared
+with the
+.Ql FOREIGN
+attribute giving the
+.Qq object library name
+and
+.Qq model name
+of the foreign function.
+For example:
+.Bd -literal -offset indent
+function my_func (x : integer; y : bit_vector; z : std_logic) return integer;
+attribute foreign of my_func : function is "VHPI my_lib my_func";
+.Ed
+.Pp
+The VHPI plugin should then call
+.Fn vhpi_register_foreignf
+to register the foreign subprogram.
+.Bd -literal -offset indent
+static void my_func_cb(const vhpiCbDataT *cb_data_p) { ... }
+
+vhpiForeignDataT my_func_data = {
+   .kind = vhpiFuncF,
+   .libraryName = "my_lib",
+   .modelName = "my_func",
+   .execf = my_func_cb,
+};
+vhpi_register_foreignf(&my_func_data);
+.Ed
+.Pp
+To use the simplified protocol the VHDL the
 .Ql FOREIGN
-attribute giving the name of the function symbol exported from the
-plugin.  For example:
+attribute should be specified with the keyword
+.Ql VHPIDIRECT
+and name of the function symbol exported from the plugin.
+For example:
 .Bd -literal -offset indent
 function my_func (x : integer; y : bit_vector; z : std_logic) return integer;
 attribute foreign of my_func : function is "VHPIDIRECT my_func";
-- 
2.39.2