doc: Add README_OSDI.md

README_OSDI.md

@@ -0,0 +1,33 @@
+# OSDI implementation for NGSPICE
+
+OSDI (Open Source Device Interface) is a simulator independent device interface, that is used by the OpenVAF compiler.
+Implementing this interface in NGSPICE allows loading Verilog-A models compiled by OpenVAF.
+The interface is fixed and does not require the compiler to know about NGSPICE during compilation.
+NGSPICE also doesn't need to know anything about the compiled models at compilation.
+Therefore, these models can be loaded dynamically at runtime.
+
+To that end the `osdi` command is provided.
+It allows loading a dynamic library conforming to OSDI.
+Example usage: `osdi diode.osdi`.
+
+If used within a netlist the command requires the `pre_` prefix.
+This ensures that the devices are loaded before the netlist is parsed.
+
+Example usage: `pre_osdi diode.osdi`
+
+If a relative path is provided to the `osdi` command in a netlist, it will resolve that path **relative to the netlist**, not relative to current working directory.
+This ensures that netlists can be simulated from any directory
+
+## Build Instructions
+
+To compile NGSPICE with OSDI support ensure that the `--enable-predictor` and `--enable-osdi` flags are used.
+The `compile_linus.sh` file enables these flags by default.
+
+
+## Example/Test Case
+
+A simple handwritten diode can be found in `test_cases/diode/diode.c`.
+In the same directory a script named `test_diode.py` is provided that will compile this model and run some example simulations.
+After the script has finished the compilation result `diode.osdi` and the netlist can then be found in `test_cases/diode/test_osdi`.
+
+