[PATCH olang v1 2/2] docs: add the C FFI section

[Carlos Maniero <carlos@maniero.me>]

This section describe both: How to call O lang from C and how to call C
from O.

Even that the "Calling O from C" may change as we evolve the discussions
if we you use or not some symbol mangle strategy it is worth to
document what we have working so far.

Signed-off-by: Carlos Maniero <carlos@maniero.me>
---
 docs/info/c-ffi.texi | 102 +++++++++++++++++++++++++++++++++++++++++++
 docs/info/olang.texi |   3 ++
 2 files changed, 105 insertions(+)
 create mode 100644 docs/info/c-ffi.texi

diff --git a/docs/info/c-ffi.texi b/docs/info/c-ffi.texi
new file mode 100644
index 0000000..719fcd5
--- /dev/null
+++ b/docs/info/c-ffi.texi
@@ -0,0 +1,102 @@
+@node C FFI
+@chapter C FFI
+
+O programming language follows C's calling conventions, meaning that every O
+function can be called by C without any extra effort.
+
+All example bellow will use @code{gcc} but you can use the compiler/linker of
+your preference.
+
+@section Calling C from O
+
+To call external code you can use the @code{extern} statement.
+
+@subsection extern
+
+@verbatim
+# file: answer.ol
+
+extern fn u32print(number: u32): u32
+
+fn main(): u8 {
+  u32print(42)
+
+  return 0
+}
+@end verbatim
+
+That way instead of defining the @code{u32print} function. It must be provided
+at the linkage step.
+
+@verbatim
+// file: u32print.c
+
+#include <stdio.h>
+
+int u32print(int number) {
+  return printf("%d\n", number);
+}
+@end verbatim
+
+@subsection Compiling without linking
+
+If you try to compile the answer.ol file you will receive the follow error:
+
+@verbatim
+olc answer.ol -o answer.o
+/usr/bin/ld: answer.o.o: in function `main':
+(.text+0x10): undefined reference to `u32print'
+collect2: error: ld returned 1 exit status
+@end verbatim
+
+That's because @code{O} tries to link by default. To assemble the code without
+linking it, you can use the @code{-c} option.
+
+@verbatim
+olc answer.ol -c -o answer.o
+@end verbatim
+
+After that you can do the same with the C file that contains the function that
+you are looking to call.
+
+@verbatim
+gcc u32print.c -c -o u32print.o
+@end verbatim
+
+And then you can link both object files into an executable:
+
+@verbatim
+gcc answer.o u32print.o -o answer
+@end verbatim
+
+@subsection Calling O from C
+
+All that is required is to set the function prototype.
+
+@verbatim
+# file: sum.ol
+
+fn sum(a: u32, b: u32): u32 {
+  return a + b
+}
+@end verbatim
+
+@verbatim
+# file: csum.c
+
+#include <stdio.h>
+
+int sum(int a, int b);
+
+int main() {
+  printf("%d\n", sum(41, 1));
+  return 0;
+}
+@end verbatim
+
+Compiling:
+
+@verbatim
+olc sum.ol -c -o sum.o
+gcc sum.o csum.c -o csum
+@end verbatim
diff --git a/docs/info/olang.texi b/docs/info/olang.texi
index eea4c29..e6339c1 100644
--- a/docs/info/olang.texi
+++ b/docs/info/olang.texi
@@ -27,6 +27,7 @@ programming language.
 * Introduction::
 * Installation::
 * Getting Started::
+* C FFI::
 * Language Specification::
 * Contribution Guide::
 @end menu
@@ -37,6 +38,8 @@ programming language.
 
 @include getting-started.texi
 
+@include c-ffi.texi
+
 @include specification.texi
 
 @include contribution-guide.texi
-- 
2.46.1