README - Erlang/OTP R9C for OSE Delta 4.4 on PowerPC750=========================================================2003-04-03 -- Peter Andersson, support@erlang.ericsson.seErlang/OTP for OSE Delta on PowerPC750 is based on the R9C release forother platforms such as Unix, Windows and VxWorks.This Erlang release contains a directory named build_erl_ose. Storedin this directory is a tar-file (erl_ose_R9C.tar) which containsmake-, configuration- and source files for building a completeErlang/OSE system for a PowerPC750 target. When the tar-file isunpacked, the following directory structure is created:	erl_utils	misc. shared code (startup files etc.)	lm/erl		for building Erlang as an OSE PRH load module	lm/ose		config. files for building an OSE executable	monolith        for building Erlang and OSE as a monolith          	port_progs	port program examples	drivers		driver examples	host		applications to run on hostOTP Applications----------------All applications that can be run on an embedded system (one thatdoesn't necessarily have access to local disk and has limited RAM) areincluded in this release. These applications will be added to the listof included OTP applications below once they have passed allassociated tests. Hence, an application that is not listed may stillwork fine, it could well be that this just hasn't been verifiedyet. Applications that will not be supported on this platform arelisted under "Omitted Applications".Included OTP Applications-------------------------kernelstdlibOmitted Applications--------------------gsemacsetkodbctoolbarGraphical interfaces--------------------For applications using graphical interfaces, only the backend part issupported.Compilers---------All compilers are expected to be run on a cross host. The OSE systemsmemory capabilities are too restricting to allow native compiling. Theexpected host system is a Sun Solaris machine, although Erlangcompilation may be done on most platforms.Supported boards and configurations-----------------------------------The following boards and configurations are fully supported:* Force PowerCore CPCI-680 with a minimum of 64 Mb memory, OSE  powercore680 BSP, OSE Delta 4.4.Hardware floating point support is not yet used in any of thesupported configurations.Configuration of OSE Delta--------------------------Erlang/OTP is dependent on the following OSE components:- Kernel- Time Out Server- Real Time Clock- Heap Manager- Shell- Pthreads- Board Support Package- Embedded File System- Internet Protocols The configuration of OSE that has been used for Erlang so far is basedon the OSE configuration examples. For details, see the Makefiles andthe .con files that are included in the build_erl_ose subdirectories of this release. Some notes:The Erlang Runtime System (ERTS) requires a minimum of 6 Mb RAM (4 Mbheap space plus 2 Mb user signal pool space) to start up and enteridle state. How much memory is required for user applications tofunction properly must be investigated for each application. Itdepends on data usage, message buffering etc.ERTS uses a local pool (specified by DEF_BLOCK in osemain.con) forallocating signals. The required size of this pool depends mainly onthe behaviour of the Erlang applications. I/O or externalcommunication (e.g. TCP/IP or port communication) uses OSE signals forpassing data between OSE processes and hence requires available poolmemory.For ERTS to work properly, the following signal sizes (specified byDEF_BLOCK) are recommended: 255, 1066, 4095, 1048575. Recommendedstack sizes are: 1023, 8191, 65535, 524288.It is quite possible that the MAXPROCS and MAX_ATTACHED values(ospp.con) need to be larger than default.It may be useful to have somewhere to store an Erlang crash dumpfile. The best choice is of course to use persistent memory (flash ordisk) if available. If there is no local filesystem or NFS,configuring a RAM disk is a good idea.This Erlang/OTP release uses the default OSE error handlerimplementation supplied by OSE Systems. No automatic restartfunctionality has been implemented.In the Makefile that comes with the release, the serial ports areconfigured according to this: COM1 is used for debug printouts bymeans of the low level dbgprintf driver in OSE (e.g. useful whenrunning the target application from a remote connection), COM2 is usedto access a local shell started with EFS (see startefs.c).There are two options for building Erlang for OSE. One is to link ERTSand OSE statically and generate one single executable from theresult. The second possibility is to build ERTS separately and use theOSE Program Handler component to load ERTS into memory as a so calledload module. However, PRH does not perform dynamic linking, onlyrelocation, as the module is loaded. Therefore the linker must be ableto resolve all references as the ERTS load module (the elf-file) isbuilt and hence common OSE and ERTS code is copied, not shared, inthis mode. Of course, the load module approach has the advantage thatit is possible to upgrade ERTS without stopping OSE.Configuration of Erlang-----------------------The Erlang Runtime System runs as one OSE process, named erts, whichin turn spawns and uses a separate process for handling select onsockets. If Erlang is started in interactive mode, two OSE processesare also started for non-blocking I/O. Erlang port programs are alsoseparate OSE processes, started when erlang:open_port/2 is called. Allprocesses are started as OSE background processes for time sharingwithout priorities.ERTS starts a separate background OSE process (the Program Server) forhandling registration and unregistration of dynamic Erlang linked-indrivers and port programs (implemented as PRH load modules).The Erlang Port Mapper Deamon (EPMD) also runs as a background OSEprocess. This process is started once, either when Erlang is startedfor the first time, or explicitly using a shell command.ERTS requires that a block, called erl_block, is defined inosemain.con. Furthermore, when building Erlang and OSE as a monolith,a dummy erl_block process (erl_tmp) should be defined inosemain.con. (ERTS uses the ID of erl_tmp to identify erl_block, seeerl.exec.c).The shell commands implemented in erl.exec.c need to be registered atOSE startup by means of a late start hook, erlHooks, in osemain.con.Environment variables for Erlang should be defined as block variablesin osemain.con. The following variables must exist and have correctvalues:HOME		home directory of the current user ROOTDIR		root directory of the Erlang installationThe following variables are optional:ERL_CRASH_DUMP	crash dump file location (default is CWD) ERL_MAX_PORTS	specifies the maximum number of Erlang ports allowed 		(default is 1024)In distributed short name mode, Erlang will use the OSE resolver tolook up host information from DNS. There are two ways to let Erlanglocate a name server. One is to specify the location of a hosts and aresolv file using variables HOSTSFILE and RESOLVFILE. Second is tospecify the IP address of a name server with variable NAMESERVER anddomain with variable DOMAIN. To learn the local host name, Erlang willread variable HOSTNAME. If this variable isn't defined, Erlang willread the host name from a name server. Hence, if Erlang is in longname mode, HOSTNAME must be defined.Building and installing Erlang/OTP for OSE Delta------------------------------------------------ To build Erlang/OTP for OSE Delta and install it on a target system,the following knowledge is expected: * Building, installing and configuring OSE Delta. * Network (TCP/IP) configuration. * Erlang basic operation and configuration.DIAB is the compiler currently used for compiling and linking, bothOSE Delta and Erlang/OTP (with exception for a few files, see knownbugs and problems). Gmake or clearmake are the expected make programs.Follow these steps to build a monolith:1. Build the Erlang/OTP release for the target in question(e.g. ose_ppc750) if this has not already been done. Follow separateinstructions for this procedure. erl_ose_P9C.tar (mentioned in theintroduction) should be located in the build_erl_ose directory afterthis step.2. Unpack the tar file.3. The monolith directory of the release contains a Makefile and a fewconfiguration and utility files for building an executable. Modify thepath to the OSE installation in the Makefile. Run gmake with flagerlopt (normal) or erldbg (debug) to compile the OSE Delta system andconfiguration files as well as the miscellaneous Erlang utility files(such as erl.exec.c). All object code will be linked and the binaryimage file (.bin) will be created.4. To install the binary image file on target, use tftp to transfer itfrom host. Make sure the image file is placed on a start address thatcorresponds to IMAGE_START in the Makefile.Follow these steps to build an ERTS load module:1-2. Follow monolith step 1-2 above to build the Erlang/OTP release.3. Use the make- and configuration files in the lm/ose directory tobuild an executable OSE image file (run 'gmake ose').4. Build an Erlang load module separately from OSE by using the samedirectives as in monolith step 3 above. The make- and configurationfiles are in the lm/erl directory. A file on elf format will becreated rather than a binary image.5. Follow monolith step 4 above to install and start OSE on target.