neuronapi: fix nrn_symbol_dataptr for top-level runtime scalars (#3815)

nrn_symbol_dataptr returned sym->u.pval for every symbol. For a NOTUSER
runtime scalar (created in HOC by e.g. `x = 42`) that union member holds
an object-data offset, not a pointer, so the returned value was a small
integer that segfaults on dereference. The real storage for such a
scalar is hoc_top_level_data[sym->u.oboff].pval, matching the NOTUSER
branch of eval() in oc/code.cpp.

Return that address for the top-level VAR/NOTUSER case so the result is a
dereferenceable double*, as the name promises; every other symbol is
unchanged. A caller can now read and write `x = 42`-style globals through
the pointer, the same as built-in USERDOUBLE scalars like t.

Adds test/api/global_scalar.cpp: a NOTUSER scalar's dataptr now
dereferences to the stored value and aliases the storage HOC reads
(cross-checked by copying into hoc_ac_), plus a USERDOUBLE round-trip.

Author: ec1dev

docs/capi.rst

@@ -714,10 +714,14 @@ Functions, objects, and the stack
 
 .. c:function:: double* nrn_symbol_dataptr(const Symbol* sym)
 
-    Get a pointer to the data for a symbol (for variables).
+    Get a pointer to the storage for a scalar variable, for direct reading and
+    writing. This covers built-in ``USERDOUBLE`` scalars such as ``t`` (time) as
+    well as runtime scalars created in HOC (e.g. ``x = 42``), whose value lives
+    in the top-level object-data array rather than at ``sym->u.pval``.
 
     :param sym: Pointer to the symbol.
-    :returns: Pointer to the symbol's data, or NULL if not applicable.
+    :returns: Pointer to the symbol's data, or the raw ``sym->u.pval`` for
+              symbols that are not top-level runtime scalars.
 
     **Usage Pattern:**
 

src/nrniv/neuronapi.cpp

@@ -251,6 +251,18 @@ int nrn_symbol_subtype(const Symbol* sym) {
 }
 
 double* nrn_symbol_dataptr(const Symbol* sym) {
+    // A NOTUSER runtime scalar (created in HOC by e.g. `x = 42`) does not store
+    // its value at sym->u.pval -- for that subtype the union member holds an
+    // object-data offset, not a pointer, so returning it hands back garbage that
+    // segfaults on dereference. The real storage is in the top-level
+    // object-data array (see the NOTUSER branch of eval() in oc/code.cpp, which
+    // reads *OPVAL(sym) == *hoc_top_level_data[sym->u.oboff].pval). Return that
+    // address so the result is a dereferenceable double*, as the name promises.
+    // Every other case (USERDOUBLE built-ins such as `t`, and the typed USER*
+    // subtypes that already alias sym->u.pval) is unchanged.
+    if (sym && sym->type == VAR && sym->subtype == NOTUSER) {
+        return hoc_top_level_data[sym->u.oboff].pval;
+    }
     return sym->u.pval;
 }
 

test/api/CMakeLists.txt

@@ -1,4 +1,11 @@
-foreach(api_test_file hh_sim.cpp netcon.cpp segment_diam.cpp sections.cpp vclamp.cpp)
+foreach(
+  api_test_file
+  global_scalar.cpp
+  hh_sim.cpp
+  netcon.cpp
+  segment_diam.cpp
+  sections.cpp
+  vclamp.cpp)
   string(REPLACE "." "_" api_test_name "${api_test_file}")
   add_executable(${api_test_name} ${api_test_file})
   cpp_cc_configure_sanitizers(TARGET ${api_test_name})

test/api/global_scalar.cpp

@@ -0,0 +1,58 @@
+// NOTE: this assumes neuronapi.h is on your CPLUS_INCLUDE_PATH
+// Exercises nrn_symbol_dataptr on a NOTUSER runtime scalar (created by HOC
+// `x = 42`). Its value is stored in the top-level object-data array, not at
+// sym->u.pval, so before the fix the returned pointer was an offset cast to a
+// pointer and dereferencing it was undefined. The pointer must now alias the
+// same storage HOC reads and writes.
+#include <cmath>
+#include <iostream>
+#include "neuronapi.h"
+
+using std::cerr;
+using std::endl;
+
+extern "C" void modl_reg(){/* No modl_reg */};
+
+static bool check(bool cond, const char* msg) {
+    if (!cond) {
+        cerr << "FAIL: " << msg << endl;
+    }
+    return cond;
+}
+
+static bool eq(double got, double want, const char* msg) {
+    if (std::fabs(got - want) > 1e-12) {
+        cerr << "FAIL: " << msg << " — got " << got << ", want " << want << endl;
+        return false;
+    }
+    return true;
+}
+
+int main(void) {
+    static const char* argv[] = {"global_scalar", "-nogui", "-nopython", nullptr};
+    nrn_init(3, argv);
+
+    bool ok = true;
+
+    // NOTUSER: a runtime scalar. Its data lives in the top-level object-data
+    // array, not at sym->u.pval -- this is the case the fix addresses.
+    nrn_hoc_call("myvar = 42");
+    double* p = nrn_symbol_dataptr(nrn_symbol("myvar"));
+    ok &= check(p != nullptr, "NOTUSER dataptr is non-null");
+    ok &= eq(*p, 42.0, "NOTUSER dataptr dereferences to 42");
+
+    // The pointer must alias the storage HOC uses: write through it, then have
+    // HOC copy myvar into the built-in hoc_ac_ and confirm HOC saw the change.
+    *p = 3.5;
+    nrn_hoc_call("hoc_ac_ = myvar");
+    double* ac = nrn_symbol_dataptr(nrn_symbol("hoc_ac_"));
+    ok &= eq(*ac, 3.5, "HOC reads the value written through the NOTUSER dataptr");
+
+    // USERDOUBLE built-in (t): dataptr already worked; make sure it still does.
+    double* t = nrn_symbol_dataptr(nrn_symbol("t"));
+    *t = 12.0;
+    nrn_hoc_call("hoc_ac_ = t");
+    ok &= eq(*ac, 12.0, "USERDOUBLE dataptr round-trips through HOC");
+
+    return ok ? 0 : 1;
+}