The R13B03 release.OTP_R13B03

1 files changed, 285 insertions, 0 deletions

diff --git a/lib/erl_interface/src/README.internal b/lib/erl_interface/src/README.internal
new file mode 100644
index 0000000000..c1f2d6863f
--- /dev/null
+++ b/lib/erl_interface/src/README.internal
@@ -0,0 +1,285 @@
+******************************************************************************
+                                 General
+******************************************************************************
+
+There are two different interfaces, the old 'erl_interface' and 'ei'.
+The old interface is to depend on the new one, not the other way arount.
+
+Erl_interface should be "thread safe", i.e. you should be able to 
+handle connections, convert data etc from different threads.
+
+Ei should be "reentrant" or "async safe", i.e. no locks should be set
+so that if an ei function is called inside an signal handler there
+could be a deadlock.
+
+VxWorks call the operating processes "tasks". These are to be handled the
+same way as Unix threads, i.e. there can only be one C node for all tasks
+using the old interface.
+
+Try to keep the documented functions, variables and symbols in sync
+between
+
+ * Documentation
+
+ * ei.h and erl_interface.h
+
+ * prog/ei_fake_prog.c and prog/erl_fake_prog.c
+
+From time to time do a
+
+  % (cd src; gmake check)
+
+(FIXME this check should be rewritten to a test case)
+
+
+******************************************************************************
+                               Directories
+******************************************************************************
+
+ * src/aux/
+
+   Support files for configure described in the next section
+
+ * src/legacy/
+
+   Old erl_interface stuff  FIXME what about thread support etc....?
+
+ * src/connect/
+
+   Create nodes, connections, communication with the other node etc
+
+ * src/decode/
+
+   Simple decode functions
+
+ * src/encode/
+
+   Simple encode functions
+
+ * src/epmd/
+
+   Handle communication with epmd
+
+ * src/registry/
+
+   Key/value database with optional mnesia back up
+
+ * src/misc/
+
+   The rest of the library
+
+ * src/prog/
+
+   erl_call and some test programs for compiling and linking
+
+ * src/not_used/
+
+   Strange, some files are not used....
+
+
+******************************************************************************
+                      Configuration support files
+******************************************************************************
+
+The build uses GNU configure and libtool. The libtool and autoconf
+package don't need to be installed to configure and build the
+sources. But in "maintainer mode" you need them to update some files
+in the source distribution.
+
+ * configure.in 
+
+   Used in maintainer mode together with "aclocal.m4" to create
+   "configure". "configure.in" is hand written and only need to
+   be updated when you change the sources to use new header files
+   or C compiler features. You may get some hints about what to
+   update using a recent autoconf package and do
+
+     % cd erl_inteface
+     % autoscan src
+
+   The result to compare with the current "configure.in" will be
+   stored in "src/configure.scan".
+
+ * aclocal.m4
+
+   This file contains macros generated by ??? appended
+   with the content of "libtool.m4" in the installed libtool
+   package. (FIXME don't know when this is to be updated and
+   why it contains so much).
+
+ * src/aux/config.guess
+ * src/aux/config.sub
+
+   Used by "configure" to form the subdirectory name
+   "cpu-vendor-os".
+
+ * src/aux/install-sh*
+
+   Used if no other BSD compatible install script is found.
+
+ * src/aux/config.h.in
+
+   Used by "configure" as a template for the resulting
+   "src/config.h". The file "config.h.in" should be
+   updated when "configure.in" is updated because the
+   new macros used in your source and this is the file
+   where they are listed. You can find out what to update
+   using
+
+     % autoheader
+
+ * ltmain.sh
+
+   This is XXX (FIXME what?)
+
+The base for the configure.in script was created with 'autoscan'.
+The base for the config.h.in file was created with 'autoheader'.
+
+
+******************************************************************************
+                          Writing source
+******************************************************************************
+
+C files in "registry" are considered users of 'ei' and should not
+include "eidef.h" or "config.h", only "ei.h".
+
+C files in "prog" could include "config.h" directly.
+
+Other C files should include "eidef.h" as the first line of
+source. "eidef.h" contains some common constants and macros and
+also includes config.h.
+
+In general avoid including other header files from header files.
+The exception is to make the protoypes complete to the user of
+this library, i.e. to include <stdio.h> to defined FILE or
+to include "ei_x_encode" to define the type ei_x_buff.
+
+The function ei_decode_term() (FIXME encode_term?) work on ETERM,
+i.e. it converts between the old erl_interface format and ei.
+Because of this it is really part of the erl_interface library,
+not the ei library.
+
+Use uint8, uint16, uint32, int8, int16, and int32 for types
+where size matters ;-) Use uint8 for buffers where we construct
+messages.
+
+NOTE!!!! Sending a "char" to macros like isupper(), isalpha() where
+the character is > 127 will cause serios problems on some
+machines/OS. The reason is that
+
+   'char' may be unsigned, i.e. the Swedish char '�' will 
+   as a number be negativ.
+
+   The implementation of isupper() and others will on some
+   machines use an array that is indexed with the incoming
+   character code. The Swedish '�' will then create an access
+   on memory outside the array!
+
+This may give a random value as a result or a segmentation
+violation error.
+
+
+******************************************************************************
+                          Global variables
+******************************************************************************
+
+There are two reasons we avoid global variables:
+
+  - It is much easier to support threads without them
+
+  - On operating systems like VxWorks the global variable is global
+    to all operating system processes.
+
+There are a few global variables that are ok
+
+  ei_x_extra	         This is set to 100 in "ei_x_encode.c" but can be
+                         changed for debugging the memory allocation.
+
+  ei_trace_distribution  Enable verbose tracing on stderr.
+
+  errno			 In the non threaded version of the lib this
+			 is a global variable.
+
+  __erl_errno 		 This is a global handled by "ei_pthreads.c"
+
+You can check for globals using something like
+
+  % nm -g ei_fake_prog | fgrep OBJT
+
+Global variables but with local scope
+
+  erl_if_ec              Global state, is ok
+
+
+******************************************************************************
+                           The "long long" story
+******************************************************************************
+
+There are some functions in the 'ei' library that uses the GCC and
+VC++ "long long" type. Unfortunately this can lead to some trouble.
+
+When user code is linked with the "libei.a" the linker will extract
+all objects files needed for resolving all symbol referenses
+found. This means that you want to follow the rule that
+
+ * To reduce executable code size we use resonably small C source
+   files. One C file is one object file.
+
+ * We try to avoid unessesary dependency. For example currently almost all
+   ei_x_encode*() functions are in the same object file. Because they all
+   use the corresponding ei_encode*() function this means using one ei_x
+   function we will link in "ei_x_encode.o" object file but also all the
+   "ei_encode*.o" object files even if they are not used.
+
+But the above is not the real trouble, memory and disk is cheap these
+days.  The real trouble is if we compile the 'ei' library using one
+compiler, usually GNU cc, and link with another linker than GNU ld or
+miss some runtime libraries that the GNU cc generated object files
+assume is on the target. For example currently on Solaris some "long
+long" operations will create a dependency to a "hidden" library
+"libgcc.a". For example in a library not released got references to
+"libgcc.a" '__ashldi3'
+
+   % nm -A libei.a | grep '__ashldi3'
+   libei.a[decode_longlong.o]: [6]  | 0| 0|NOTY |GLOB |0 |UNDEF |__ashldi3
+   libei.a[decode_ulonglong.o]: [5] | 0| 0|NOTY |GLOB |0 |UNDEF |__ashldi3
+
+We can accept that a dependecy is created for code linked with
+"libei.a" that actually use 'ei' long long functions. But if we
+arrange the 'ei' source badly using a non "long long" functions from
+'ei' will still link in an object file that need "libgcc.a". One
+example is that in plain R9C the ei_x_encode_longlong() function is
+located in the file "ei_x_encode.c". So if any "long long" ei_x
+function is used we have an unessesary dependency on
+"ei_encode_longlong.o" and then need to link with GNU ld on with the
+user code or explicitely link with "libgcc.a". The situation can be
+visible in in plain R9C using
+
+     % nm -A erl_interface-3.4/lib/libei.a | \
+	  grep 'longlong' | fgrep -v 'longlong.o'
+
+As an possibly alternative to the current solution we may include the
+object files inside the "libgcc.a" archive in the "libei.a" archive.
+The "libgcc.a" that is assumed to be used when linking can be found
+using
+
+  % gcc -print-libgcc-file-name
+
+Some links about problems and solutions using "libgcc.a"
+
+  http://www.gnu.org/software/gcc/gcc-3.0/libgcc.html
+  http://www.gnu.org/software/libc/FAQ.html
+
+The license for "libgcc.a" is a bit special and not located on the
+official sites. You have to look in the source file for the "libgcc.a"
+you use. The file is named "libgcc.c". If you don't know what gcc that
+was used for the build of for example 'r9c' you can use
+
+  % otp_build_env -o r9c | perl -ne '/(gcc-[\d\.]+)/ and print "$1\n"'
+
+Then to view the lincense do
+
+  % less `find /usr/local/share/src/gcc-REL/ -name "libgcc*.c"`
+
+
+********************************* EOF ****************************************