[GR-15997] Document our implementation of FFI

Author: eregon

doc/contributor/ffi.md

@@ -0,0 +1,26 @@
+# FFI
+
+We have our own implementation of FFI, implemented entirely in Ruby + Truffle
+NFI.
+
+Using the FFI gem C extension would be suboptimal because Sulong uses Truffle
+NFI to call native methods. Truffle NFI is implemented with `libffi`. The FFI C
+extension uses its own `libffi` to call native functions. This means we would
+use Truffle NFI's `libffi` to call the C extension `libffi` functions, adding
+overhead on every call to the C extension `libffi` functions.
+
+FFI is also one way to avoid C extensions altogether, so it makes sense to not
+require C extension support for gems using FFI.
+
+## Structure
+
+* `lib/truffle/ffi`: Unchanged Ruby files from the gem.
+* `lib/truffle/truffle/ffi_backend`: our Ruby + Truffle NFI backend for FFI,
+  which replaces the C extension and has the same API.
+* `lib/truffle/ffi.rb` coordinates `require`-ing the above.
+* `spec/ffi`: Specs from the FFI gem.
+* `src/main/ruby/truffleruby/core/truffle/ffi`: Implementation of
+  `Truffle::FFI::Pointer`, which is also used in core and is aliased to
+  `FFI::Pointer` once `"ffi"` is required. `Truffle::FFI::Pointer` should
+  therefore have the same API as `FFI::Pointer` in the FFI gem.
+* `tool/import-ffi.sh`: Imports files from a checkout of the FFI gem.

doc/legal/legal.md

@@ -141,7 +141,7 @@ files.
 
 #### FFI
 
-TruffleRuby includes parts of the FFI gem 1.9.25. The FFI gem is copyright
+TruffleRuby includes parts of the FFI gem 1.11.1. The FFI gem is copyright
 2008-2016, Ruby FFI project contributors, and covered by the three-clause BSD
 licence (see `ffi.txt`).
 

doc/user/security.md

@@ -138,7 +138,9 @@ Consider potential vulnerabilities in your system `libssl`.
 
 ## FFI
 
-We are not aware of any known vulnerabilities.
+Number | Description | Their Mitigation | Test | Our Mitigation
+--- | --- | --- | --- | ---
+CVE-2018-1000201 | A DLL loading issue can be hijacked on Windows when a `Symbol` is used for the library name | Treat Symbols the same as Strings in `ffi_lib` | | Applied the same mitigation, by using a version of FFI which fixed this vulnerability
 
 # Notes on hashing
 

doc/user/truffleruby-additions.md

@@ -77,6 +77,13 @@ and set.
 
 `AtomicReference` is marshalable.
 
+## FFI
+
+TruffleRuby includes a built-in implementation of [Ruby-FFI](https://github.com/ffi/ffi),
+compatible with version 1.11.1 of the `ffi` gem. This should be transparent: you can
+just install the `ffi` gem as normal, and it will use our built-in implementation,
+regardless of the version of the `ffi` gem.
+
 ## Polyglot programming
 
 The `Polyglot` and `Java` modules provides access to the polyglot programming