installation.tex

\chapter{Установка и лицензирование Simics} \label{chap:installation-notes}

В данное приложение включена информация по лицензированию и установке Simics в учебной лаборатории. Наиболее полная информация по данному вопросу содержится в документе «Simics Installation Guide»~\cite{installation}, который идёт в поставке со всеми пакетами Simics (файл \texttt{installation-guide.pdf}).

Приводимые ниже инструкции были собраны для Simics версии 4.6 для хозяйской системы Linux 64 бит, рекомендуемой для всех пользователей. Для ОС Linux 32 бит инструкции изменяются незначительно; для ОС Windows они применимы после учёта особенностей графического процесса инсталляции.

\section{Академическая программа Wind River Simics}

Компания Intel предлагает Simics бесплатно для некоммерческих исследований и обучения в выбранных университетах через академическую программу Intel Simics Academic Program. Для включения нового университета в эту программу необходимо согласие на поддержку начинания одного ментора --- сотрудника Intel. 

Дополнительная информация об истории и статусе академической программы Simics~\cite{engblom-academic-simics}.

\subsection{Условия использования}

Использование Simics по академической программе должно строго соответствовать условиям соглашения, т.е. быть ограничено учебной и/или некоммерческой научно-исследовательской деятельностью. В случае возникновения необходимости проведения коммерческих исследований или разработок необходимо обратиться к представителям Wind River для получения нового соглашения и другого типа лицензии.

Держатель лицензии от участвующего университета обязан донести эту информацию до всех пользователей инсталляции и контролировать выполнение ими условий соглашения, в том числе с помощью административных и технических мер.

Подробные детали об условиях и ограничениях академической программы содержатся в документе <<Intel Academic SLA>>, поставляемом с копией Simics для университетов.

\section{Установка файлов и запрос лицензии}

\subsection{Пакеты}

Simics распространяется в формате пакетов --- набора файлов, реализующих одну или несколько типов моделируемых систем или функциональность самого симулятора. Каждый пакет имеет свой фиксированный номер. Пакет \textnumero 1000 --- это Simics Base, содержащий базовую функциональность симулятора. Все остальные пакеты являются дополнениями к нему.

Дистрибутив пакета --- это файл с именем вида \texttt{simics-pkg-1000-4.6.34-linux64.tar}.  Здесь 1000 --- номер пакета, 4.6.34 --- версия пакета, linux64 --- архитектура хозяйской системы. Каждый дистрибутив каждого пакета зашифрован собственным ключом, состоящим из 32 символов. Дистрибутивы и их ключи получите у спонсора вашей академической программы.

Для установки всех необходимых файлов выполняется следующая процедура. Часть команд может потребовать наличия прав администратора.

\begin{enumerate}
\item Разархивируйте все пакеты *.tar:
\begin{lstlisting}
$ for f in simics-pkg-*.tar; do tar xf $f; done
\end{lstlisting}
\item В созданной директории \texttt{simics-4.6-install} запустите скрипт установки:
\begin{lstlisting}
$ cd simics-4.6-install
# ./install-simics.pl
\end{lstlisting} 
    
\item Введите ключи шифрования для каждого номера пакета, который планируется установить:
\begin{lstlisting}
-> Looking for Simics packages in current directory...
Enter a decryption key for package-1000-4.6.34-linux64.tar.gz.tf,
or Enter to [Abort]: введите или скопируйте ключ
\end{lstlisting} 

\item На вопрос, какие из пакетов требуется установить, ответьте <<All packages>>:
\begin{lstlisting}
install-simics can install the following packages:
 Number  Name          Type    Version  Host     Package
   1     Simics-Base   simics  4.6.34   linux64  package-1000
   2     Eclipse       addon   4.6.16   linux64  package-1001
   3     All packages
Please enter the numbers of the packages you want to install, as in "1 4 3"
Package numbers, or Enter to [Abort]:  3
\end{lstlisting}
    
\item На вопрос о директории назначения введите абсолютный путь или оставьте значение по умолчанию:
\begin{lstlisting}
Enter a destination directory for installation, or Enter
for [/opt/simics]:  [Путь установки или Enter]
\end{lstlisting}

\item Подтвердите начало установки, выбрав <<y>>.

\item При введении правильных ключей дистрибутивы будут расшифрованы и установлены в указанную при установке директорию --- в ней должны появиться подпапки с файлами из пакетов Simics.
\begin{lstlisting}
-> Decrypting package-1000-4.6.34-linux64.tar.gz.tf
-> Testing package-1000-4.6.34-linux64.tar.gz
-> Installing package-1000-4.6.34-linux64.tar.gz
-> Decrypting package-1001-4.6.16-linux64.tar.gz.tf
-> Testing package-1001-4.6.16-linux64.tar.gz
-> Installing package-1001-4.6.16-linux64.tar.gz

===============================

install-simics has finished installing the packages and will now
configure them.

No previous Simics installation was found. If you wish to configure
the newly installed Simics from a previous installation not found by
this script, you can do so by running the 'addon-manager' script in
the Simics installation with the option --upgrade-from:
    ./bin/addon-manager --upgrade-from /previous/install/

install-simics has installed the following add-on package:
   Eclipse  4.6.16  /opt/simics/simics-eclipse-4.8.26
\end{lstlisting}

\item На вопрос о регистрации расширений (\abbr add-on) ответьте <<y>>:
\begin{lstlisting}
Do you wish to make these add-on packages available in
Simics-Base 4.6.34? (y, n) [y]:  y
\end{lstlisting}   
\end{enumerate}

После успешного завершения файлы Simics были скопированы на ваш диск. Следующий шаг --- получение лицензии для их запуска. Он описывается далее.

\subsection{Получение lmhostid}

Для получения файла лицензии необходимо сгенерировать и передать число, так называемый lmhostid.

\paragraph{Об именовании сетевых интерфейсов.} На момент написания данного материала утилиты из состава Simics не поддерживали получение корректного lmhostid на системах, использующих схему «стабильного именования» сетевых интерфейсов. Вместо традиционных для Linux имён \texttt{eth0}, \texttt{eth1} и т.д. сетевым картам выдаются имена, зависящие от производителя и физического расположения в системе, например, \texttt{enp6s0}, \texttt{enp11s0}. 
Методы решения данной проблемы описаны в~\cite{predictable-iface-names}.

\begin{enumerate}
    \item Установите пакет \texttt{lsb-core} на системе. Для Debian и Ubuntu это выполняется командой:
    
    \texttt{\# apt-get install lsb-core}
         
    \item Для получения lmhostid на сервере, \textit{который будет использоваться для запуска демона лицензий}, выполните команду:
    
\begin{lstlisting}
$ /opt/simics/simics-4.6.34/flexnet/linux64/bin/lmutil lmhostid
lmutil - Copyright (c) 1989-2011 Flexera Software, Inc. All Rights Reserved.
The FlexNet host ID of this machine is ""602fe934a369 422fe934a36c ""
Only use ONE from the list of hostids.
\end{lstlisting}

Выданное число (в примере выше <<602fe934a369>>) --- это lmhostid. Если чисел выдано несколько, то используйте только одно из них.
    
\end{enumerate}

\subsection{Заполнение заявки}

Для получения пакетов, ключей к ним, а также подписания лицензионного соглашения об участии в академической программе Wind River Simics обратитесь к вашему спонсору или пройдите процедуру, описанную в~\cite{engblom-academic-simics}.

\section{Настройка сервера лицензий}

Сервер лицензий --- отдельная программа, запущенная на постоянно включенном компьютере и определяющая, какие модели и в каком количестве будут доступны в компьютерном классе.

\subsection{Файл лицензии}

Получаемый от производителя файл лицензии --- это текстовый документ, содержащий информацию о сроке действия, ограничениях количества одновременно запускаемых копий и поддерживаемых расширениях приложения. Пример содержимого для начала этого файла:

\begin{lstlisting}
# Simics 4.6 licence for the Simics Academic Program
#
# University:        Moscow Institute of Physics and Technology
# Contact:           academic.contact@university.edu
# Sponsor:           sponsor.contact@sponsor.com
# Licensing Contact: licencing.contact@licencer.com
#
SERVER  lic.university.edu lmhostid
VENDOR simics /opt/simics/simics-4.6/simics-4.6.100/flexnet/linux64/bin
#
FEATURE simics simics 4.6 28-feb-2014 50 BD47D265FA68 \
VENDOR_STRING=intel;academic HOSTID=ANY BORROW TS_OK \
SIGN="0441 6AFA 450C BDBE E4D7 E125 1042 EEFF 04B5 767A ABCD \
        5088 80DB D912 292E 4FD5 22DD 22D0 D55F 5B25 4818"
<...>
\end{lstlisting}

Не изменяйте никаких строк этого файла, кроме имени сервера лицензий (строка с \texttt{SERVER}) и пути к каталогу с файлом вендор-демона (строка \texttt{VENDOR}, должна указывать на положение файлов с именами \texttt{lmgrd} и \texttt{simics}). Сохраните копию файла в надёжном месте. Запишите дату окончания действия лицензии для последующей своевременной инициации процедуры её обновления.

\subsection{Запуск сервера}

Для запуска серевера лицензий используется программа \texttt{lmgrd}, поставляемая с базовым пакетом\footnote{Варианты этой программы, полученные из других источников, не рекомендуются и не поддерживаются.}. Её расположение: \texttt{<simics-base>/flexnet/linux64/bin/lmgrd}.

Пример последовательности команд для ручного запуска \texttt{lmgrd}:
\begin{lstlisting}
$ cd /opt/simics/simics-4.6/simics-4.6.100/flexnet/linux64/bin/
$ ./lmgrd -c /opt/simics/simics-4.6/simics-4.6.100/licenses/simics.lic
\end{lstlisting}

В данном случае процесс остаётся в консоли (не уходит в фоновый режим) и печатает диагностику в консоль. Для остановки достаточно послать ему сигнал с помощью клавиш Ctrl-C.

Для автоматического запуска и остановки процесса \texttt{lmgrd} при включении и выключении системы рекомендуется использовать init-скрипт в стиле инициализации SysV. Пример такого скрипта: \url{https://gist.github.com/grigory-rechistov/11142235}, также он приведён в секции~\ref{sec:initscript}.

\subsection{Проверка работоспособности}

Запустите демон лицензии. Затем запустите копию Simics из любого workspace на этой же системе. В случае успеха приложение успешно откроет своё окно или покажет приглашение командной строки \texttt{simics>}.

\section{Расположение файлов и сервера лицензий при подключении по сети}

По умолчанию все файлы Simics размещаются в директории \texttt{/opt/simics}. Если необходимо обеспечить запуск симулятора на нескольких компьютерах, подсоединённых по сети, рекомендуется разместить эти файлы установки в файловой системе, доступной по сети, например, по протоколам NFS или CIFS. Таким образом, клиентские машины смогут переиспользовать структуру инсталляции без необходимости её копирования на локальные диски, что упростит её поддержку и выполнение обновлений. Настройка сетевой файловой системы выходит за рамки данного руководства; необходимую информацию можно найти, например, в~\cite{nfs}.

\subsection{Финальный вид инсталляции}

На рис.~\ref{fig:install-overview} приведена рекомендуемая схема соединения систем и расположения служб для работы Simics на всех компьютерах учебного класса или лаборатории. В данном примере сервер для запуска демона лицензий отделён от сервера общих файлов; на практике они могут быть одной и той же системой.

\begin{figure}[htbp]
\centering
\begin{tikzpicture}[>=latex, font=\small]
    
    \node[draw] (lic-file) {simics-00AA-2014.lic};
    \node[draw, below = 0.25cm of lic-file] (lmgrd) {lmgrd демон};
    \node[above = 0.25cm of lic-file] (lic-host) {lic.university.edu};
    \node[draw, fit = (lic-file) (lmgrd) (lic-host)] (lic-server) {};    
    
    \node[draw, below = 2cm of lic-server] (installation) {/opt/simics/...};
    \node[draw, below = 0.25cm of installation] (nfs) {NFS демон};
    \node[above = 0.25cm of installation] (nfs-host) {nfs.university.edu};
    \node[draw, fit = (installation) (nfs) (nfs-host)] (nfs-server) {};
    
    \node[draw, right = 3cm of lic-file] (simics01) {Симуляция};
    \node[draw, below = 0.25cm of simics01] (lab01-client) {Клиент Simics};
    \node[above = 0.25cm of simics01] (lab01-host) {lab01.university.edu};
    \node[draw, fit = (simics01) (lab01-client) (lab01-host)] (lab01) {};

    \node[draw, below = 1.5cm of lab01] (simics02) {Симуляция};
    \node[draw, below = 0.25cm of simics02] (lab02-client) {Клиент Simics};
    \node[above = 0.25cm of simics02] (lab02-host) {lab02.university.edu};
    \node[draw, fit = (simics02) (lab02-client) (lab02-host)] (lab02) {};

    \node[draw, below = 1.5cm of lab02] (simics03) {Симуляция};
    \node[draw, below = 0.25cm of simics03] (lab03-client) {Клиент Simics};
    \node[above = 0.25cm of simics03] (lab03-host) {lab03.university.edu};
    \node[draw, fit = (simics03) (lab03-client) (lab03-host)] (lab03) {};
    
    \draw[->] (lmgrd.east) -- (lab01-client.west);
    \draw[->] (lmgrd.east) -- (lab02-client.west);
    \draw[->] (lmgrd.east) -- (lab03-client.west);
    
    \coordinate[right = 1cm of installation]  (midpoint);
    \draw[<-] (installation) -| (midpoint);
    \draw[->] (midpoint) |- (simics01);
    \draw[->] (midpoint) |- (simics02);
    \draw[->] (midpoint) |- (simics03);
    
\end{tikzpicture}
\caption{Расположение и функции узлов инсталляции Simics}\label{fig:install-overview}
\end{figure}

\subsection{Решение возникших проблем}

Следует отметить, что процесс \texttt{lmgrd} рекомендуется запускать из-под непривилегированного пользователя, т.е. не root. Кроме того, он должен быть в состоянии найти файл с т.н. программой vendor-daemon, которая для Simics называется \texttt{simics} и находится в той же директории, что и \texttt{lmgrd}. Поэтому запуск должен демона происходить из этой же директории, или же она должна быть внесена в переменную окружения \$PATH.

Ниже описаны некоторые часто встречающиеся неполадки и способы их устранить.
\begin{description}
    \item[Невозможно стартовать lmgrd.] Проверьте флаги файла \texttt{lmgrd} на признак исполняемости; при необходимости выставите его с помощью \texttt{chmod +x lmgrd}.
    
    \item[lmgrd выходит сразу после запуска.] Возможные причины: 1) одна копия \texttt{lmgrd} уже запущена; 2) не найден файл лицензии; 3) не найден файл с вендор-демоном \texttt{simics}; 4) запуск на системе с неправильным lmhostid; 5) Файл блокироки /tmp/locksimics существует и недоступен на запись. Прочитайте вывод об ошибке, оставшийся после выхода демона, и исправьте указанную в нём причину.

    \item[Нет подключения к демону лицензии локально.] При этом Simics на некоторое время зависает, а затем сообщает код ошибки подключения к серверу лицензий. Проверьте, что настройки Simics указывают на правильный файл.
    
    \item[Simics зависает в самом начале загрузки.] Проверьте, что переменная окружения \$DISPLAY или настроена правильно, или неопределена (при запусках без графического интерфейса).
    
    \item[Нет подключения к демону лицензии по сети.]  Проверьте, что между машинами с работающим \texttt{lmgrd} и запускаемым Simics нет фаервола. Откройте порты 28000 и 28001 в фаерволе, если он присутствует и необходим.
    
    \item[Демон лицензий не работает после перезагрузки сервера.] Проверьте, что процесс демона запущен. Проверьте, что файл /tmp/locksimics не существует. Настройте корректное завершения процесса \texttt{lmgrd} при остановке ОС сервера лицензий.
    
    \item[Исчерпано число лицензий.] Выключите излишние, ненужные запущенные симуляции.
    
\end{description}

\clearpage
\section{init скрипт для старта и остановки демона лицензий}\label{sec:initscript}
Данный скрипт \texttt{lmgrd-simics} должен быть размещён в /etc/inid.d с правом исполнения, затем для Debian-систем должен быть включён с помощью команды:

\texttt{\# update-rc.d lmgrd-simics defaults}

Он доступен по ссылке \url{https://gist.github.com/grigory-rechistov/11142235}.

\begin{lstlisting}
#! /bin/sh
### BEGIN INIT INFO
# Provides:          lmgrd-simics
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Control Flexera lmgrd license daemon for Simics installation
# Description:       Control start/stop of lmgrd entry for Simics
#
### END INIT INFO

# Author: Grigory Rechistov (<grigory.rechistov@phystech.edu>)
#

# Do NOT "set -e"

# PATH should only include /usr/* if it runs after the mountnfs.sh script
PATH=/sbin:/usr/sbin:/bin:/usr/bin
DESC="lmgrd for Simics"
SIMICSDIR=/opt/simics/simics-4.6/simics-4.6.100
LICENSEFILE=/opt/simics/simics-4.6/simics-4.6.100/licenses/simics.lic # change to your license file
NAME=lmgrd
VENDORDAEMON=simics
DAEMONDIR=$SIMICSDIR/flexnet/linux64/bin
SCRIPTNAME=/etc/init.d/$NAME
DAEMON=$DAEMONDIR/$NAME

PIDFILE=/var/tmp/$NAME.pid
LOCKFILE=/var/tmp/locksimics
LOGFILE=/var/tmp/lmgrd-simics.log

# Exit if the package is not installed
[ -x "$DAEMON" ] || exit 0

# Read configuration variable file if it is present
[ -r /etc/default/$NAME ] && . /etc/default/$NAME

# Load the VERBOSE setting and other rcS variables
. /lib/init/vars.sh

# Define LSB log_* functions.
# Depend on lsb-base (>= 3.2-14) to ensure that this file is present
# and status_of_proc is working.
. /lib/lsb/init-functions

#
# Function that starts the daemon/service
#
do_start()
{
  # Return
  #   0 if daemon has been started
  #   1 if daemon was already running
  #   2 if daemon could not be started
  start-stop-daemon --start -c daemon:daemon --make-pidfile --pidfile $PIDFILE -d $DAEMONDIR --exec $DAEMON -- -c $LICENSEFILE -l +$LOGFILE || return 2
  pidof $NAME > $PIDFILE # This is lame; but lmgrd about itself does not create anything.
}

#
# Function that stops the daemon/service
#
do_stop()
{
  # Return
  #   0 if daemon has been stopped
  #   1 if daemon was already stopped
  #   2 if daemon could not be stopped
  #   other if a failure occurred
  start-stop-daemon --stop --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name $NAME
  RETVAL="$?"
  [ "$RETVAL" = 2 ] && return 2
  # Many daemons don't delete their pidfiles when they exit.
  rm -f $PIDFILE
        rm -f $LOCKFILE
  return "$RETVAL"
}

#
# Function that sends a SIGHUP to the daemon/service
#
do_reload() {
  #
  # If the daemon can reload its configuration without
  # restarting (for example, when it is sent a SIGHUP),
  # then implement that here.
  #
  start-stop-daemon --stop --signal 1 --quiet --pidfile $PIDFILE --name $NAME
  return 0
}

case "$1" in
  start)
  [ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME"
  do_start
  case "$?" in
    0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
    2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
  esac
  ;;
  stop)
  [ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME"
  do_stop
  case "$?" in
    0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
    2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
  esac
  ;;
  status)
       status_of_proc "$DAEMON" "$NAME" && exit 0 || exit $?
       ;;
  #reload|force-reload)
  #
  # If do_reload() is not implemented then leave this commented out
  # and leave 'force-reload' as an alias for 'restart'.
  #
  #log_daemon_msg "Reloading $DESC" "$NAME"
  #do_reload
  #log_end_msg $?
  #;;
  restart|force-reload)
  #
  # If the "reload" option is implemented then remove the
  # 'force-reload' alias
  #
  log_daemon_msg "Restarting $DESC" "$NAME"
  do_stop
  case "$?" in
    0|1)
    do_start
    case "$?" in
      0) log_end_msg 0 ;;
      1) log_end_msg 1 ;; # Old process is still running
      *) log_end_msg 1 ;; # Failed to start
    esac
    ;;
    *)
      # Failed to stop
    log_end_msg 1
    ;;
  esac
  ;;
  *)
  #echo "Usage: $SCRIPTNAME {start|stop|restart|reload|force-reload}" >&2
  echo "Usage: $SCRIPTNAME {start|stop|status|restart|force-reload}" >&2
  exit 3
  ;;
esac
:
\end{lstlisting}


\iftoggle{webpaper}{
    \printbibliography[title={Литература}]
}{}