diff options
Diffstat (limited to 'erts/etc/vxworks/README.VxWorks')
| -rw-r--r-- | erts/etc/vxworks/README.VxWorks | 350 |
1 files changed, 0 insertions, 350 deletions
diff --git a/erts/etc/vxworks/README.VxWorks b/erts/etc/vxworks/README.VxWorks deleted file mode 100644 index 299e35b513..0000000000 --- a/erts/etc/vxworks/README.VxWorks +++ /dev/null @@ -1,350 +0,0 @@ - - %CopyrightBegin% - - Copyright Ericsson AB 1997-2009. All Rights Reserved. - - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. - - %CopyrightEnd% - ------------------------------------------------------------------------ -README, Erlang/OTP R11B for VxWorks on PPC860 and PPC603 ------------------------------------------------------------------------ -20060515 -- Patrik Nyblom, [email protected] - -R11B is a libraries only release for VxWorks. Only the libraries of -erl_interface (ei+erl_inteface) and ic are expected to be used. Still -the whole erlang system is distributed, although no support will be -given for anything else but the libraries. The information in this -file still applies to the full erlang distribution and parts of it are -therefore somewhat irrelevant to commercial users. - - -Included OTP applications -------------------------- - -appmon -asn1 -compiler -cosEvent -cosNotification -cosTime -cosTransaction -debugger -erl_interface -erts -eva [1] -ic -inets [2] -jinterface -kernel -mesh -mnemosyne -mnesia [1] -mnesia_session -orber -os_mon -pman -runtime_tools -sasl -snmp -stdlib -tools -tv - -[1] Only ram_copies work, The VxWorks filesystems are not - reliable enough for disk_copies to be fully supported. -[2] CGI scripts do not work on VxWorks. - -Omitted applications --------------------- - -crypto -emacs -etk -gs -odbc -parsetools -toolbar -ssl -megaco -webtools - -As `crypto' and `ssl' provides cryptographic functionality to `inets' -and `snmp', the latter applications will not handle cryptography on -VxWorks. - -Graphical interfaces --------------------- - -For applications using graphical interfaces, only the backend part works. - -Compilers ---------- - -All compilers are expected to be run on a cross host. The VxWorks -systems memory capabilities are too restricting to allow native -compiling. The expected host system is a Sun Solaris machine, although -Erlang compilation may be done on most platforms. - -Supported boards and configuration (only libraries supported) ----------------------------------- -The following boards and configurations are supported: - -* Force PowerCore 603 with Force pcore603 BSP and VxWorks 3.5.1 (no - SENS or SENS 1.1 + SPR23938) and a minimum of 32 Mb memory. - -* Force Powercore 750 with Force pcore750 BSP and VxWorks 3.5.1 (no - SENS or SENS 1.1 + SPR23938) and a minimum of 32 Mb memory. - -* PSS Core PPC860 processors, only erl_interface (too small main memory). - -Most PowerPC boards with FPU are expected to work, but will need to be -tested by OTP to be fully supported. - -The PPC603 build has been compiled with Wind River's `-mlongcall' -flag (SPR25893) to support arbitrary function calls across more -than 32 MB of memory. - -The PPC860 (PowerQuicc) has no FPU and requires a separate build. - -For Erlang to run, the Wind kernel has to be configured with a minimum -of these variables defined in config.h (or by the Tornado -configuration tool): - - INCLUDE_ANSI_ALL - INCLUDE_ENV_VARS - INCLUDE_EXC_HANDLING - INCLUDE_EXC_TASK - INCLUDE_FLOATING_POINT - INCLUDE_FORMATTED_IO - INCLUDE_IO_SYSTEM - INCLUDE_LOADER - INCLUDE_NETWORK - INCLUDE_NET_INIT - INCLUDE_NET_SHOW - INCLUDE_NET_SYM_TBL or INCLUDE_STANDALONE_SYM_TBL - INCLUDE_PIPES - INCLUDE_POSIX_FTRUNC - INCLUDE_RLOGIN or INCLUDE_TELNET (for pty's only) - INCLUDE_SELECT - INCLUDE_SEM_BINARY - INCLUDE_SEM_COUNTING - INCLUDE_SEM_MUTEX - INCLUDE_SHELL (*) - INCLUDE_SHOW_ROUTINES - INCLUDE_SIGNALS - INCLUDE_STARTUP_SCRIPT (*) - INCLUDE_STDIO - INCLUDE_SYM_TBL - INCLUDE_TASK_HOOKS - INCLUDE_TASK_VARS - INCLUDE_TTY_DEV - INCLUDE_UNLOADER - INCLUDE_NFS or INCLUDE_RAMDRV or INCLUDE_DOSFS (i.e. a file system, - possibly read-only) (**) - -(*) Needed for the example startup script, not actually needed in production if - erlang is set up by a c routine called from usrConfig.c. -(**) INCLUDE_NFS usually requires the NFS_USER_ID and NFS_GROUP_ID variables - to be set in config.h - -As an erlang system may open a lot of files, it is recommended to raise the -default NUM_FILES variable to something like 256 in config.h like this: - #ifdef NUM_FILES - #undef NUM_FILES - #endif - #define NUM_FILES 256 - -The SENS stack *has* to be of version 1.1 or higher, 1.0 is *not* -supported and will not work reliably. Upgrades as well as the patch -for SPR23938 can be found at www.wrs.com (i.e. WindSurf). Also, the -following constants in $WIND_BASE/target/h/netBufLib.h has to be -raised to a value of at least four times the default: - - NUM_NET_MBLKS - NUM_64 - NUM_128 - NUM_256 - NUM_512 - NUM_1024 - NUM_2048 - - NUM_SYS_64 - NUM_SYS_128 - NUM_SYS_256 - NUM_SYS_512 - -Use the show routines mbufShow and netStackSysPoolShow to verify that -these pools are not exhausted. - -Installation ------------- - -To install Erlang on a VxWorks card, the following knowledge is -expected: - -* VxWorks installation and configuration. - -* Network (TCP/IP) configuration. - -* Erlang basic operation and configuration. - -There is no specific install script for erlang on the VxWorks -platform. There is however an example VxWorks startup file named -erts-5.0.1/bin/erl_script.sam under the root of an unpacked -release. There may of course be other things to do in the start -script, like using the rdate program in the erlang distribution to get -a correct date and set the TIMEZONE variable. - -Please consult the "Embedded System" documentation for further -information on installation. - -Known Bugs and problems ------------------------ - -We have found the VxWorks/NFS client file system to be unreliable. -Important file operations like rename, ftruncate, cd and unlink -doesn't always work as expected. Therefore more complex file using -parts of OTP, like DETS and disk based mnesia tables cannot be used -reliably with NFS. Lowering the NFS cache size (global variable -nfsCacheSize) to 512 gives a more reliable NFS client, but to disk -base the mnesia tables over NFS is still not a good idea, especially -as disk based mnesia tables are not supported on VxWorks. Another -problem with VxWorks file systems is that the error codes they produce -are not consistent. We have worked around this problem by mapping the -codes to POSIX ones, by doing this we make the VxWorks Erlang platform -behave similarly to the UNIX and Windows implementations. - -The rename and ftruncate operations over NFS are emulated using -copying of files. This is mainly for our own test suites and it is not -recommended to use file:rename and/or file:ftruncate on NFS file -systems in production. - -Floating point operations is somewhat faulty. For instance, testing -floating point numbers for equality should be done with care. This is -actually not a bug, IEEE specifies no equality among floating point -numbers. - -Memory handling ---------------- - -Please read the erl_set_memory_block(3) manual page in the ERTS -documentation for information concerning memory handling in the erlang -emulator. Also please observe that reclaim.o has to be loaded and -reclaim_init() called before any other erlang routines are loaded and -started. If one wish to use the resource reclamation routines in other -programs, refer to the header file in `erts-5.0.1/include/reclaim.h'. -Including that file in your C source makes malloc/realloc/free and -open/fopen/socket/close etc be redefined to routines that makes the -memory and files be free'd/closed when the task exits. Still, -reclaim_init() *has* to be called before any program that uses this is -started. - -Using heart ------------ - -The default behavior of the heart object file that is part of the -distribution is that it reboots the target when the Erlang process -hasn't given it a heart beat in 60 seconds. The normal heart beat rate -is one beat per five seconds. This makes an effective "software -watchdog" but there is really no substitute for the real thing --- a -hardware watchdog. If you want to add a hardware watchdog to the -system please contact us for directions. If you want to disable the -reboot you may set the environment variable HEART_DONT_REBOOT (see the -example erlang start script, erl). Please note that if you DO want the -card to reboot you mustn't define HEART_DONT_REBOOT at all. E.g. to -disable heart reboot you may include the following line in the start -script (as is indeed the case with the example start script). - - putenv "HEART_DONT_REBOOT=1" - -A few words on writing port program and dynamically loaded drivers for VxWorks ------------------------------------------------------------------------------- - -VxWorks has one name-space for all symbols. This makes it harder to -write C programs whose global symbols doesn't interfere with each -other. It is a good rule to avoid all globally visible symbols that -are not absolutely necessary. Due to these facts we use the following -naming rules that are crucial to follow. (there are more issues -involved but the issues described here is a good beginning). - -Port programs must have a function with the same name as the object -file. E.g. if you have an object file named `port_test.o' it must -contain a globally visible function named `port_test'. This is the -function that will be called when you output data from Erlang to the -port. (The object file, in this example, should be named -`port_test.o', but `port_test' will also do). - -Also, in an embedded system, it is recommended to load the port -program into the system before the port program is used. This is to -avoid the real time degradation dynamical linking in runtime would -introduce. Use VxWorks command ld < "port_prg" to accomplish this. - -Dynamically linked drivers must have a function with the same name as -the object file with the added suffix `_init'. We recommend the use of -the macro DRIVER_INIT in `driver.h'. E.g. if you have an object file -named `echo_drv.eld' it must contain a globally visible function -`echo_drv_init'. (The object file, in this example, should be named -`echo_drv.eld' (`eld' is short for Erlang Loadable Driver), but -`echo_drv.o' and `echo_drv' will both also do). It is also very -important to initialize all unused function pointer in the -`driver_entry' struct to NULL (see example below). - -Example of dynamically linked driver ------------------------------------- - -#include <stdio.h> -#include "driver.h" - -static int erlang_port; -static long echo_start(); -static int echo_stop(), echo_read(); - -static struct driver_entry echo_driver_entry = { - null_func, - echo_start, - echo_stop, - echo_read, - null_func, - null_func, - "echo_drv", - null_func -}; - -int DRIVER_INIT(echo_drv)(void *handle) -{ - erlang_port = -1; - - echo_driver_entry.handle = handle; - return (int) &echo_driver_entry; -} - -static long echo_start(long port,char *buf) -{ - if (erlang_port != -1) { - return -1; - } - - erlang_port = port; - return port; -} - -static int echo_read(long port, char *buf, int count) -{ - return driver_output(erlang_port, buf, count); -} - -static int echo_stop() -{ - return erlang_port = -1; -} |