diff options
Diffstat (limited to 'lib/erl_interface/src/README.internal')
| -rw-r--r-- | lib/erl_interface/src/README.internal | 285 |
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 **************************************** |