From aa90ad958b21a777c171a794c2a352c099e55c21 Mon Sep 17 00:00:00 2001 From: Omar Awile Date: Mon, 17 Aug 2020 16:18:31 +0200 Subject: [PATCH 1/2] Added documentaiton for BBCOREPOINTER --- docs/index.rst | 1 + .../userdoc/MemoryManagement/bbcorepointer.md | 93 +++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 docs/userdoc/MemoryManagement/bbcorepointer.md diff --git a/docs/index.rst b/docs/index.rst index 7d671fc2a..6d6fa047c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ Welcome to CoreNEURON's documentation! :caption: User documentation: userdoc/BinaryFormat/BinaryFormat.md + userdoc/MemoryManagement/bbcorepointer.md .. toctree:: :maxdepth: 2 diff --git a/docs/userdoc/MemoryManagement/bbcorepointer.md b/docs/userdoc/MemoryManagement/bbcorepointer.md new file mode 100644 index 000000000..a37fb33c0 --- /dev/null +++ b/docs/userdoc/MemoryManagement/bbcorepointer.md @@ -0,0 +1,93 @@ + +## Transferring dynamically allocated data between NEURON and CoreNEURON + + +User-allocated data can be managed in NMODL using the `POINTER` type. It allows the +programmer to reference data that has been allocated in HOC or in VERBATIM blocks. This +allows for more advanced data-structures that are not natively supported in NMODL. + +Since NEURON itself has no knowledge of the layout and size of this data it cannot +transfer `POINTER` data automatically to CoreNEURON. Furtheremore, in many cases there +is no need to transfer the data between the two instances. In some cases, however, the +programmer would like to transfer certain user-defined data into CoreNEURON. The most +prominent example are random123 RNG stream parameters used in synapse mechanisms. To +support this use-case the `BBCOREPOINTER` type. Variables that are declared as +`BBCOREPOINTER` behave exactly the same as `POINTER` but are additionally taken into account +when NEURON is serializing mechanism data (for file writing or direct-memory transfer). +For NEURON to be able to write (and indeed CoreNEURON to be able to read) `BBCOREPOINTER` +data, the programmer has to additionally provide two C functions that are called as part +of the serialization/deserialization. + +``` +static void bbcore_write(double* x, int* d, int* d_offset, int* x_offset, _threadargsproto_); + +static void bbcore_read(double* x, int* d, int* d_offset, int* x_offset, _threadargsproto_); +``` + +The implementation of `bbcore_write` and `bbcore_read` determines the serialization and +deserialization of the per-instance mechanism data referenced through the various +`BBCOREPOINTER`s. + +NEURON will call `bbcore_write` twice per mechanism instance. In a first sweep, the call is used to +determine the required memory to be allocated on the serialization arrays. In the second sweep the +call is used to fill in the data per mechanism instance. + +The functions take following arguments + +* `x`: A `double` type array that will be allocated by NEURON to fill with real-valued data. In the + first call, `x` is NULL as it has not been allocated yet. +* `d`: An `int` type array that will be allocated by NEURON to fill with integer-valued data. In the + first call, `d` is NULL as it has not been allocated yet. +* `x_offset`: The offset in `x` at which the mechanism instance should write its real-valued + `BBCOREPOINTER` data. In the first call this is an output argument that is expected to be updated + by the per-instance size to be allocated. +* `d_offset`: The offset in `x` at which the mechanism instance should write its integer-valued + `BBCOREPOINTER` data. In the first call this is an output argument that is expected to be updated + by the per-instance size to be allocated. +* `_threadargsproto_`: a macro placeholder for NEURON/CoreNEURON data-structure parameters. They + are typically only used through generated defines and not by the programmer. The macro is defined + as follows: + +``` +#define _threadargsproto_ \ + int _iml, int _cntml_padded, double *_p, Datum *_ppvar, ThreadDatum *_thread, NrnThread *_nt, \ + double _v +``` + +Putting all of this together, the following is a minimal MOD using BBCOREPOINTER: + +``` +TITLE A BBCOREPOINTER Example + +NEURON { + BBCOREPOINTER my_data +} + +ASSIGNED { + my_data +} + +: Do something interesting with my_data ... + +VERBATIM +static void bbcore_write(double* x, int* d, int* x_offset, int* d_offset, _threadargsproto_) { + if (x) { + double* x_i = x + *x_offset; + x_i[0] = _p_my_data[0]; + x_i[1] = _p_my_data[1]; + } + *x_offset += 2; // reserve 2 doubles on serialization buffer x +} + +static void bbcore_read(double* x, int* d, int* x_offset, int* d_offset, _threadargsproto_) { + assert(!_p_my_data); + double* x_i = x + *x_offset; + // my_data needs to be allocated somehow + _p_my_data = (double*)malloc(sizeof(double)*2); + _p_my_data[0] = x_i[0]; + _p_my_data[1] = x_i[1]; + *x_offset += 2; +} +ENDVERBATIM +``` + From d466c715bfd9bac63ff5f740390e71c02a2da60d Mon Sep 17 00:00:00 2001 From: Omar Awile Date: Mon, 17 Aug 2020 17:01:58 +0200 Subject: [PATCH 2/2] Fixed little issue --- docs/userdoc/MemoryManagement/bbcorepointer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userdoc/MemoryManagement/bbcorepointer.md b/docs/userdoc/MemoryManagement/bbcorepointer.md index a37fb33c0..0d669e66d 100644 --- a/docs/userdoc/MemoryManagement/bbcorepointer.md +++ b/docs/userdoc/MemoryManagement/bbcorepointer.md @@ -11,7 +11,7 @@ transfer `POINTER` data automatically to CoreNEURON. Furtheremore, in many cases is no need to transfer the data between the two instances. In some cases, however, the programmer would like to transfer certain user-defined data into CoreNEURON. The most prominent example are random123 RNG stream parameters used in synapse mechanisms. To -support this use-case the `BBCOREPOINTER` type. Variables that are declared as +support this use-case the `BBCOREPOINTER` type was introduced. Variables that are declared as `BBCOREPOINTER` behave exactly the same as `POINTER` but are additionally taken into account when NEURON is serializing mechanism data (for file writing or direct-memory transfer). For NEURON to be able to write (and indeed CoreNEURON to be able to read) `BBCOREPOINTER`