aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/embedded/starting.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /system/doc/embedded/starting.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'system/doc/embedded/starting.xml')
-rw-r--r--system/doc/embedded/starting.xml249
1 files changed, 249 insertions, 0 deletions
diff --git a/system/doc/embedded/starting.xml b/system/doc/embedded/starting.xml
new file mode 100644
index 0000000000..ddeaeb8bdf
--- /dev/null
+++ b/system/doc/embedded/starting.xml
@@ -0,0 +1,249 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ 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.
+
+ </legalnotice>
+
+ <title>Starting an Embedded System</title>
+ <prepared>Martin Bj&ouml;rklund</prepared>
+ <responsible>Bjarne D&auml;cker</responsible>
+ <docno></docno>
+ <approved>Bjarne D&auml;cker</approved>
+ <checked></checked>
+ <date>1997-10-17</date>
+ <rev>D</rev>
+ <file>starting.sgml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+ <p>This chapter describes how an embedded system is started.
+ There are four programs involved, and they all normally reside
+ in the directory <c><![CDATA[<ERL_INSTALL_DIR>/bin]]></c>. The only
+ exception is the program <c>start</c>, which may be located
+ anywhere, and also is the only program that must be modified by
+ the user.
+ </p>
+ <p>In an embedded system there usually is no interactive shell.
+ However, it is possible for an operator to attach to the
+ Erlang runtime system by giving the command <c>to_erl</c>. He is
+ then connected to the Erlang shell, and may give ordinary Erlang
+ commands. All interaction with the system through this shell is
+ logged in a special directory.
+ </p>
+ <p>Basically, the procedure is as follows. The program
+ <c>start</c> is called when the machine is started. It calls
+ <c>run_erl</c>, which sets things up so the operator can attach
+ to the system. It calls <c>start_erl</c> which calls the
+ correct version of <c>erlexec</c> (which is located in
+ <c><![CDATA[<ERL_INSTALL_DIR>/erts-EVsn/bin]]></c>) with the correct
+ <c>boot</c> and <c>config</c> files.
+ </p>
+ </section>
+
+ <section>
+ <title>Programs</title>
+
+ <section>
+ <title>start</title>
+ <p>This program is called when the machine is started. It may
+ be modified or re-written to suit a special system. By
+ default, it must be called <c>start</c> and reside in
+ <c><![CDATA[<ERL_INSTALL_DIR>/bin]]></c>. Another start program can be
+ used, by using the configuration parameter <c>start_prg</c> in
+ the application <c>sasl</c>.</p>
+ <p>The start program must call <c>run_erl</c> as shown below.
+ It must also take an optional parameter which defaults to
+ <c><![CDATA[<ERL_INSTALL_DIR>/bin/start_erl.data]]></c>.
+ </p>
+ <p>This program should set static parameters and environment
+ variables such as <c>-sname Name</c> and <c>HEART_COMMAND</c>
+ to reboot the machine.
+ </p>
+ <p>The <c><![CDATA[<RELDIR>]]></c> directory is where new release packets
+ are installed, and where the release handler keeps information
+ about releases. See <c>release_handler(3)</c> in the
+ application <c>sasl</c> for further information.
+ </p>
+ <p>The following script illustrates the default behaviour of the
+ program.
+ </p>
+ <code type="none"><![CDATA[
+#!/bin/sh
+# Usage: start [DataFile]
+#
+ROOTDIR=/usr/local/otp
+
+if [ -z "$RELDIR" ]
+then
+ RELDIR=$ROOTDIR/releases
+fi
+
+START_ERL_DATA=${1:-$RELDIR/start_erl.data}
+
+$ROOTDIR/bin/run_erl /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl @@@
+ $ROOTDIR $RELDIR $START_ERL_DATA" > /dev/null 2>&1 &]]></code>
+ <p>The following script illustrates a modification where the
+ node is given the name <c>cp1</c>, and the environment variables
+ <c>HEART_COMMAND</c> and <c>TERM</c> have been added to the
+ above script.
+ </p>
+ <code type="none"><![CDATA[
+#!/bin/sh
+# Usage: start [DataFile]
+#
+HEART_COMMAND=/usr/sbin/reboot
+TERM=sun
+export HEART_COMMAND TERM
+
+ROOTDIR=/usr/local/otp
+
+if [ -z "$RELDIR" ]
+then
+ RELDIR=$ROOTDIR/releases
+fi
+
+START_ERL_DATA=${1:-$RELDIR/start_erl.data}
+
+$ROOTDIR/bin/run_erl /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl @@@
+ $ROOTDIR $RELDIR $START_ERL_DATA -heart -sname cp1" > /dev/null 2>&1 &]]></code>
+ <p>If a diskless and/or read-only client node is about to start the
+ <c>start_erl.data</c> file is located in the client directory at
+ the master node. Thus, the <c>START_ERL_DATA</c> line should look
+ like:
+ </p>
+ <code type="none">
+CLIENTDIR=$ROOTDIR/clients/clientname
+START_ERL_DATA=${1:-$CLIENTDIR/bin/start_erl.data}</code>
+ </section>
+
+ <section>
+ <title>run_erl</title>
+ <p>This program is used to start the emulator, but you will not
+ be connected to the shell. <c>to_erl</c> is used to connect to the
+ Erlang shell.
+ </p>
+ <code type="none">
+Usage: run_erl pipe_dir/ log_dir "exec command [parameters ...]"</code>
+ <p>Where <c>pipe_dir/</c> should be <c>/tmp/</c>
+ (<c>to_erl</c> uses this name by default) and <c>log_dir</c> is
+ where the log files are written. <c>command [parameters]</c> is
+ executed, and everything written to stdin and stdout is logged in
+ the <c>log_dir</c>.
+ </p>
+ <p>In the <c>log_dir</c>, log files are written. Each logfile
+ has a name of the form: <c>erlang.log.N</c> where N is a
+ generation number, ranging from 1 to 5. Each logfile holds up to
+ 100kB text. As time goes by the following logfiles will be found
+ in the logfile directory</p>
+ <code type="none">
+erlang.log.1
+erlang.log.1, erlang.log.2
+erlang.log.1, erlang.log.2, erlang.log.3
+erlang.log.1, erlang.log.2, erlang.log.3, erlang.log.4
+erlang.log.2, erlang.log.3, erlang.log.4, erlang.log.5
+erlang.log.3, erlang.log.4, erlang.log.5, erlang.log.1
+... </code>
+ <p>with the most recent logfile being the right most in each row
+ of the above list. That is, the most recent file is the one with
+ the highest number, or if there are already four files, the one
+ before the skip.
+ </p>
+ <p>When a logfile is opened (for appending or created) a time
+ stamp is written to the file. If nothing has been written to
+ the log files for 15 minutes, a record is inserted that says
+ that we're still alive.
+ </p>
+ </section>
+
+ <section>
+ <title>to_erl</title>
+ <p>This program is used to attach to a running Erlang runtime system,
+ started with <c>run_erl</c>.
+ </p>
+ <code type="none">
+Usage: to_erl [pipe_name | pipe_dir]</code>
+ <p>Where <c>pipe_name</c> defaults to <c>/tmp/erlang.pipe.N</c>.
+ </p>
+ <p>To disconnect from the shell without exiting the Erlang
+ runtime system, type <c>Ctrl-D</c>.
+ </p>
+ </section>
+
+ <section>
+ <title>start_erl</title>
+ <p>This program starts the Erlang emulator with parameters
+ <c>-boot</c> and <c>-config</c> set. It reads data about where
+ these files are located from a file called <c>start_erl.data</c>
+ which is located in the <c><![CDATA[<RELDIR>]]></c>. Each new release
+ introduces a new data file. This file is automatically
+ generated by the release handler in Erlang.
+ </p>
+ <p>The following script illustrates the behaviour of the
+ program.</p>
+ <code type="none">
+#!/bin/sh
+#
+# This program is called by run_erl. It starts
+# the Erlang emulator and sets -boot and -config parameters.
+# It should only be used at an embedded target system.
+#
+# Usage: start_erl RootDir RelDir DataFile [ErlFlags ...]
+#
+ROOTDIR=$1
+shift
+RELDIR=$1
+shift
+DataFile=$1
+shift
+
+ERTS_VSN=`awk '{print $1}' $DataFile`
+VSN=`awk '{print $2}' $DataFile`
+
+BINDIR=$ROOTDIR/erts-$ERTS_VSN/bin
+EMU=beam
+PROGNAME=`echo $0 | sed 's/.*\\///'`
+export EMU
+export ROOTDIR
+export BINDIR
+export PROGNAME
+export RELDIR
+
+exec $BINDIR/erlexec -boot $RELDIR/$VSN/start -config $RELDIR/$VSN/sys $* </code>
+ <p>If a diskless and/or read-only client node with the <c>sasl</c>
+ configuration parameter <c>static_emulator</c> set to <c>true</c>
+ is about to start the <c>-boot</c> and <c>-config</c> flags must be
+ changed. As such a client can not read a new <c>start_erl.data</c>
+ file (the file is not possible to change dynamically) the boot and
+ config files is always fetched from the same place (but with a new
+ contents if a new release has been installed). The
+ <c>release_handler</c> copies this files to the <c>bin</c> directory
+ in the client directory at the master nodes whenever a new release
+ is made permanent.
+ </p>
+ <p>Assuming the same <c>CLIENTDIR</c> as above the last line should
+ look like:</p>
+ <code type="none">
+exec $BINDIR/erlexec -boot $CLIENTDIR/bin/start @@@
+ -config $CLIENTDIR/bin/sys $* </code>
+ </section>
+ </section>
+</chapter>
+