1996 2009 Ericsson AB. 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.

Starting an Embedded System

Martin Björklund Bjarne Däcker Bjarne Däcker
1997-10-17
D starting.sgml

## Introduction

This chapter describes how an embedded system is started. There are four programs involved, and they all normally reside in the directory <ERL_INSTALL_DIR>/bin. The only exception is the program start, which may be located anywhere, and also is the only program that must be modified by the user.

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 to_erl. 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.

Basically, the procedure is as follows. The program start is called when the machine is started. It calls run_erl, which sets things up so the operator can attach to the system. It calls start_erl which calls the correct version of erlexec (which is located in <ERL_INSTALL_DIR>/erts-EVsn/bin) with the correct boot and config files.

## Programs

### start

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 start and reside in <ERL_INSTALL_DIR>/bin. Another start program can be used, by using the configuration parameter start_prg in the application sasl.

The start program must call run_erl as shown below. It must also take an optional parameter which defaults to <ERL_INSTALL_DIR>/bin/start_erl.data.

This program should set static parameters and environment variables such as -sname Name and HEART_COMMAND to reboot the machine.

The <RELDIR> directory is where new release packets are installed, and where the release handler keeps information about releases. See release_handler(3) in the application sasl for further information.

The following script illustrates the default behaviour of the program.

`#!/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 &`

The following script illustrates a modification where the node is given the name cp1, and the environment variables HEART_COMMAND and TERM have been added to the above script.

`#!/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 &`

If a diskless and/or read-only client node is about to start the start_erl.data file is located in the client directory at the master node. Thus, the START_ERL_DATA line should look like:

`CLIENTDIR=$ROOTDIR/clients/clientname START_ERL_DATA=${1:-$CLIENTDIR/bin/start_erl.data}`

### run_erl

This program is used to start the emulator, but you will not be connected to the shell. to_erl is used to connect to the Erlang shell.

`Usage: run_erl pipe_dir/ log_dir "exec command [parameters ...]"`

Where pipe_dir/ should be /tmp/ (to_erl uses this name by default) and log_dir is where the log files are written. command [parameters] is executed, and everything written to stdin and stdout is logged in the log_dir.

In the log_dir, log files are written. Each logfile has a name of the form: erlang.log.N 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

`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 ...`

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.

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.

### to_erl

This program is used to attach to a running Erlang runtime system, started with run_erl.

`Usage: to_erl [pipe_name | pipe_dir]`

Where pipe_name defaults to /tmp/erlang.pipe.N.

To disconnect from the shell without exiting the Erlang runtime system, type Ctrl-D.

### start_erl

This program starts the Erlang emulator with parameters -boot and -config set. It reads data about where these files are located from a file called start_erl.data which is located in the <RELDIR>. Each new release introduces a new data file. This file is automatically generated by the release handler in Erlang.

The following script illustrates the behaviour of the program.

`#!/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 $*`

If a diskless and/or read-only client node with the sasl configuration parameter static_emulator set to true is about to start the -boot and -config flags must be changed. As such a client can not read a new start_erl.data 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 release_handler copies this files to the bin directory in the client directory at the master nodes whenever a new release is made permanent.

Assuming the same CLIENTDIR as above the last line should look like:

`exec $BINDIR/erlexec -boot $CLIENTDIR/bin/start @@@ -config $CLIENTDIR/bin/sys $*`