Foreign function stuff documented

1 files changed, 79 insertions, 0 deletions

diff --git a/doc/ffi.md b/doc/ffi.md
new file mode 100644
index 0000000..3a6091f
--- /dev/null
+++ b/doc/ffi.md
@@ -0,0 +1,79 @@
+Foreign Function Interface
+==========================
+
+Elymas supports loading of shared object based libraries (`*.so`) utilizing the standard libc facilities.
+This support is only available in the `shared` interpreter, which different from all other interpreters,
+dynamically links against libc.
+
+    sys .so ":" via
+    "/lib/x86_64-linux-gnu/libm.so.6" :dlopen not { "Failed to load." die } rep
+    "sin" "d" "d" :resolveFunction =*sin
+    0 31 range { 10.0 div sin dump } each
+
+
+`sys .so .dlopen`
+-----------------
+
+Takes a filename of a shared object from the stack and loads that shared object. A handle is returned
+but can savely be ignored except to test it against zero, which would signify an error.
+
+`sys .so .resolveFunction`
+--------------------------
+
+Takes a function name, a string describing function arguments and a string describing the return type
+from the stack. It resolves the name within all currently loaded objects, and returns an elymas function
+object which wraps the underlying foreign function.
+
+The input specification string consists of single characters, each describing the type of one input
+argument.
+
+* `p` - A pointer argument.
+* `i` - An integer (of any width).
+* `f` - A float.
+* `d` - A double.
+* `s` - A string. A pointer to a zero-terminated string is passed to the C-function.
+* `b` - A buffer. A pointer the beginning of the string contents is passed to the C-function.
+
+When specifying the return type of the function, integer widths matter, hence the following
+options are available.
+
+* `v` - No return value
+* `p` - Pointer return value
+* `u8` - `uint8_t` return value
+* `u16` - `uint16_t` return value
+* `u32` - `uint32_t` return value
+* `u64` - `uint64_t` return value
+* `i8` - `int8_t` return value
+* `i16` - `int16_t` return value
+* `i32` - `int32_t` return value
+* `i64` - `int64_t` return value
+* `s` - String return value (will be copied)
+* `f` - float return value
+* `d` - double return value
+
+
+`sys .so .rawContentAddress`
+----------------------------
+
+Returns the address of the first byte of a string. This can be handy to build complex C structures
+within a string memory and then passing the pointer to a foreign function.
+
+`sys .so .peekString`
+---------------------
+
+Takes an address and scans that address for a C-style zero-terminated string
+(of some implementation defined maximum length). This string is subsequently returned.
+
+`sys .so .freeze`
+-----------------
+
+A binary created by `sys .freeze` will have no dynamic dependencies, hence libc is not available. If you
+want to use dynamic libraries in your binary, use `sys .so .freeze` which will create an ELF binary which
+is dynamically linked against libc. The loaded libc is then used to call `dlopen` and `dlsym` to load
+further libraries. The `shared` interpreter has been created with `sys .so .freeze`.
+
+
+Libraries interfaced so far
+---------------------------
+
+* `ffi .pq` - PostgreSQL