doc/install.tex

   1 % $Id$
   2
   3 \newpage
   4 \section{Installation}
   5 \label{install}
   6
   7 \subsection{Übersicht über den Quellcode}
   8
   9 Am Beispiel der Verzeichnisstruktur der \LL-Version v1.0.0-rc1 soll
  10 der Inhalt des tar-Files vorgestellt werden:
  11
  12 \begin{code}
  13 llcf-v1/
  14 llcf-v1/doc/
  15 llcf-v1/install/
  16 llcf-v1/src/
  17 llcf-v1/src/drivers/
  18 llcf-v1/src/drivers/sja1000/
  19 llcf-v1/src/drivers/tricore/
  20 llcf-v1/src/test/
  21 \end{code}
  22
  23 Die Verzeichnisse beinhalten im Einzelnen:
  24
  25 \begin{description}
  26 \item[doc] Diese Dokumentation (als LaTeX Quelltext oder nur als PDF).
  27 \item[install] Scripts und Dateien zum automatischen Laden der Module.
  28 \item[src] Den Quellcode der \LL-Module.
  29 \item[src/drivers] Unterverzeichnis für CAN-Netzwerktreiber.
  30 \item[src/drivers/sja1000] Philips SJA1000 Netzwerktreiber.
  31 \item[src/drivers/tricore] Infineon TwinCAN TC1920 Netzwerktreiber.
  32 \item[src/test] Verschiedene Testrahmen und Beispielcode.
  33 \end{description}
  34
  35 \subsection{Kompilieren des Quellcodes}
  36
  37 \subsubsection{Systemvoraussetzungen}
  38
  39 Die \LL-Module werden zur Laufzeit in den Linux-Kernel geladen. Dazu
  40 muss sichergestellt sein, dass die Module unter den selben
  41 Randbedingungen erzeugt wurden, wie der Kernel und die dazugehörigen
  42 Module, die bereits erstellt wurden.\\
  43
  44 Insbesondere müssen übereinstimmen:
  45
  46 \begin{itemize}
  47 \item Die Version des Linux Kernel (z.B. 2.4.31)
  48 \item Die Version des verwendeten Compilers (z.B. gcc 3.3)
  49 \end{itemize}
  50
  51 Die Information, welcher Kernel auf dem System gerade läuft, lässt sich
  52 folgendermaßen ermitteln:
  53
  54 \begin{code}
  55 hartko@pplinux1:~> cat /proc/version
  56 Linux version 2.4.26 (root@vwagwockfe40) (gcc version 2.95.4) #2 Mi Mär 30 14:13:59 CEST 2005
  57 \end{code}
  58
  59
  60 Beim Übersetzen des Kernel müssen die folgenden Randbedingungen
  61 gegeben sein:
  62
  63 \begin{itemize}
  64 \item Linux Kernel Version 2.4 (Eine Anpassung für Kernel 2.6 ist in Arbeit)
  65 \item Der Kernel Module Loader muss konfiguriert sein (CONFIG\_KMOD)
  66 \item Das Dateisystem procfs muss konfiguriert sein (CONFIG\_PROC\_FS)
  67 \end{itemize}
  68
  69 Bei einer Linux-Installation (z.B. Knoppix) sollten zumindest die
  70 \verb+include+-Dateien des laufenden Kernel (typischerweise unter
  71 \verb+/usr/src/linux+) vorhanden sein. Ist dieses nicht der Fall, muss
  72 ein aktueller Kernel 2.4 heruntergeladen (www.kernel.org), ausgepackt,
  73 compiliert und installiert werden.
  74
  75 \subsubsection{Kompilieren der \LL-Module}
  76 \label{compile}
  77
  78 Das Kompilieren der \LL-Kernelmodule geschieht im Verzeichnis \verb+src+
  79 mit Aufruf des Befehles \verb+make+. Dabei wird als Compiler 'cc' und
  80 als Verzeichnis für den Kernel-Quellcode \verb+/usr/src/linux+
  81 angenommen.
  82
  83 Soll ein anderer Compiler verwendet werden oder befinden sich die zu
  84 verwendenden Kernel-Quellen an einer anderen Stelle, so können diese
  85 Standard-Einstellungen geändert werden. Z.B. mit\\
  86
  87 \verb+make CC=gcc-2.95 KERNELDIR=/usr/src/linux-2.4.26+\\
  88
  89 Zusätzlich besteht die Möglichkeit, die \LL-Kernelmodule mit einer
  90 DEBUG-Option zu übersetzen. Mit dem Module-Parameter \verb+debug=1+
  91 kann zum Lade-Zeitpunkt des Moduls eine erweiterte Informationsausgabe
  92 im Kernel-Log (beispielweise in \verb+/var/log/kern.log+) erreicht
  93 werden. Siehe dazu auch der Hinweis in Kapitel \ref{modparms}. An
  94 einem realen Fahrzeug mit mehreren hundert CAN-Frames pro
  95 Sekunde sollte man auf diese Möglichkeit allerdings verzichten! Der
  96 Parameter, um die DEBUG-Funktionalität mit einzukompilieren lautet
  97 \verb+DEBUG=-DDEBUG+ - also wird \verb+make+ z.B. so aufgerufen:\\
  98
  99 \verb+make CC=gcc-2.95 KERNELDIR=/usr/src/linux-2.4.26 DEBUG=-DDEBUG+\\
 100
 101 Nach dem Aufruf von \verb+make+ sollten verschiedene Kernel-Module
 102 (Dateiendung \verb+.o+) im \verb+src+-Verzeichnis erzeugt worden
 103 sein. Darunter z.B. die Datei \verb+can.o+.
 104
 105 \subsubsection{Kompilieren der CAN-Netzwerk-Module}
 106
 107 Analog zu den \LL-Modulen wird beispielsweise im Verzeichnis
 108 \verb+src/drivers/sja1000+ der Befehl \verb+make+ ausgeführt. Das
 109 Kernel-Modul für die PC104/ISA-Anbindung des SJA1000-Controllers heißt
 110 \verb+sja1000-isa.o+. Der Treiber für das iGate (Jaybrain GW2) heißt
 111 \verb+sja1000-gw2.o+.
 112
 113 \subsubsection{Kompilieren der Testanwendungen}
 114
 115 Die Testanwendungen benötigen keinen konkreten Bezug zum Kernel und
 116 können einfach mit \verb+make+ im Verzeichnis \verb+src/test+
 117 übersetzt werden.
 118
 119 \subsection{Installation der Module}
 120
 121 Derzeit existiert noch keine Make-Umgebung, die durch ein einfaches
 122 \verb+make install+ die Installation der Module ausführen kann. Daher
 123 diese etwas ausführlichere Anleitung.
 124
 125 \subsubsection{Kopieren der Module}
 126
 127 Um die Module zu installieren muss, man sich als Benutzer 'root' im
 128 System anmelden. Die ladbaren Module werden unter Linux in einer
 129 Verzeichnisstruktur in \verb+/lib/modules/<kernelversion>+
 130 abgelegt. Für dieses Beispiel gehen wir von einer Kernelversion 2.4.31
 131 aus.
 132
 133 \begin{itemize}
 134 \item Neues Verzeichnis für die \LL-Module anlegen: \mbox{\tt mkdir
 135 /lib/modules/2.4.31/llcf}
 136 \item \LL-Module kopieren (in \verb+src+):
 137 \mbox{\tt cp *.o /lib/modules/2.4.31/llcf}
 138 \item ggf. Treiber-Module kopieren z.B.: \mbox{\tt cp sja1000-isa.o
 139 /lib/modules/2.4.31/llcf}
 140 \item Modulabhängigkeiten aktualisieren: \mbox{\tt depmod -a}
 141 \end{itemize}
 142
 143 Dieses Verfahren ist auch für CAN-Netzwerk-Treibermodule anzuwenden,
 144 die nicht im \LL-tar-File enthalten sind. Siehe Kapitel \ref{hardware}.
 145
 146 \subsubsection{Automatisches Laden und Starten der Module}
 147 \label{autoload}
 148
 149 Der Module-Loader unter Linux kann - bei entsprechender Konfiguration
 150 - Kernelmodule automatisch laden. D.h. beim Öffnen eines \LL-Sockets
 151 können die entsprechenden Kernelmodule geladen werden, ohne die
 152 \LL-Module fest in den Kernel einbinden zu müssen.\\
 153
 154 Zudem können Modulen beim Ladevorgang Parameter übergeben
 155 werden. Diese Funktionalitäten werden durch die Konfigurationseinträge
 156 in der Datei \verb+/etc/modules.conf+ realisiert.\\
 157
 158 Für das \LL\ wurde als Ausgangsbasis im Verzeichnis \verb+install+
 159 eine Datei \verb+llcf+ angelegt, die ..
 160
 161 \begin{itemize}
 162 \item ... an die Datei \verb+/etc/modules.conf+ anzuhängen ist ODER
 163 \item ... z.B. bei Debian-System nach \verb+/etc/modutils+ zu kopieren
 164 ist
 165 \end{itemize}
 166
 167 Bei Debian-Systemen muss nach dem Kopiervorgang oder bei Änderungen
 168 der Datei \verb+/etc/modutils/llcf+ das Script
 169 \verb+update-modules.modutils+ aufgerufen werden.\\
 170
 171 Ein Ausschnitt aus der Datei \verb+llcf+ ohne die Modul-Parameter für
 172 die unterstütze CAN Hardware:
 173
 174 \begin{code}
 175 # Low Level CAN Framework
 176 # Copyright (c) 2005 Volkswagen Group Electronic Research
 177 #
 178 # uncomment and edit lines for your specific hardware!
 179 #
 180 # On debian systems copy this file to the directory
 181 # /etc/modutils and say 'update-modules.modutils'.
 182 # Other systems: Add this content to /etc/modules.conf
 183
 184 # protocol family PF_CAN
 185 alias net-pf-30 can
 186
 187 # protocols in PF_CAN
 188 alias can-proto-1 can-tp16
 189 alias can-proto-2 can-tp20
 190 alias can-proto-3 can-raw
 191 alias can-proto-4 can-bcm
 192 alias can-proto-5 can-mcnet
 193 alias can-proto-6 can-isotp
 194 alias can-proto-7 can-bap
 195
 196 # protocol module options
 197 #option tp_gen printstats=1
 198
 199 # virtual CAN devices
 200 alias vcan0 vcan
 201 alias vcan1 vcan
 202 alias vcan2 vcan
 203 alias vcan3 vcan
 204
 205 (..)
 206 \end{code}
 207
 208 Für die verwendete CAN-Hardware sind in der Datei \verb+llcf+ auch
 209 Modul-Parameter vorhanden. Dabei sind besonders die Einstellungen der
 210 Bit-Timing-Register (btr) zum Zeitpunkt des Modul-Ladens zu
 211 beachten. Entsprechend der verwendeten Hardware sind hier Änderungen
 212 durchzuführen.
 213
 214 \begin{code}
 215 # CAN hardware (uncomment the currently used)
 216
 217 ##> Trajet GW2
 218 #alias can0 sja1000-gw2
 219 #alias can1 sja1000-gw2
 220 #alias can2 sja1000-gw2
 221 #alias can3 sja1000-gw2
 222 #options sja1000-gw2 speed=500,100,500,100
 223 #options sja1000-gw2 btr=0xC03D,0xC4F9,0xC03D,0xC4F9
 224
 225 ##> Peak System hardware (ISA/PCI/Parallelport Dongle)
 226 ##> to set BTR-values to PCI-devices see Peak System documentation
 227 ##> e.g. echo "i 0x4914 e" > /dev/pcan0
 228 #alias can0 pcan
 229 #alias can1 pcan
 230 #alias can2 pcan
 231 #options pcan type=isa,isa io=0x2C0,0x320 irq=10,5 btr=0x4914,0x4914
 232 #options pcan type=epp btr=0x4914
 233 #options parport_pc io=0x378 irq=7
 234
 235 ##> EMS Wuensche CPC-Card
 236 #options cpc-card btr=0x4914,0x4914
 237 #
 238 ##> add the following lines to /etc/pcmcia/config.opts (!)
 239 ## EMS Wuensche CPC-Card CAN Interface
 240 #device "cpc-card_cs"
 241 #  module "cpc-card", "cpc-card_cs"
 242 #  card "EMS Dr. Thomas Wuensche CPC-Card CAN Interface"
 243 #  version "EMS_T_W", "CPC-Card", "*", "*"
 244 #  bind "cpc-card_cs"
 245 \end{code}
 246
 247 Für die häufig verwendeten Philips SJA1000 CAN-Controller ergeben sich
 248 bei einem Controller-Takt von 16 MHz beispielsweise folgende Werte für
 249 die Bit-Timing-Register (\verb+btr=<xx>+):
 250 \begin{description}
 251 \item[0x4914] 100 kBit
 252 \item[0x4114] 500 kBit
 253 \item[0x4014] 1000 kBit
 254 \end{description}
 255
 256 \subsubsection{Automatisches Hochfahren der CAN-Netzwerk-Interfaces}
 257
 258 Die CAN-Netzwerk-Interfaces können wie jedes andere Netzwerk-Interface
 259 auch mit dem Befehl \verb+ifconfig+ hoch- und heruntergefahren werden.
 260 \begin{code}
 261 hartko@pplinux1:~> ifconfig can0 up
 262 hartko@pplinux1:~> ifconfig can0 down
 263 \end{code}
 264
 265 Für das automatische Hoch- und Herunterfahren der
 266 CAN-Netzwerk-Interfaces wurde im Verzeichnis \verb+install+
 267 eine Datei \verb+can_if+ angelegt, die in das Verzeichnis
 268 \verb+/etc/init.d+ zu kopieren ist. In dieser Datei sind drei Variable
 269 angelegt, die die zu bearbeitenden Interfaces bestimmen.
 270
 271 \begin{code}
 272 CAN_IF="can0 can1"
 273 VCAN_IF="vcan0 vcan1"
 274 PROBE=""
 275 \end{code}
 276
 277 In diesem Beispiel werden beim Starten des Systems die Interfaces
 278 'can0', 'can1', 'vcan0' und 'vcan1' hochgefahren.
 279
 280 Mit \verb+/etc/init.d/can_if start+ kann man als Benutzer 'root' die
 281 Interfaces starten und mit \verb+/etc/init.d/can_if stop+ wieder
 282 herunterfahren (beispielsweise, wenn neue Kernel-Module installiert
 283 werden sollen und die alten mit \verb+rmmod <modulname>+ entfernt
 284 werden sollen).\\
 285
 286 \label{probe}
 287 Die Variable \verb+PROBE+ ermöglicht es dem Anwender, zum
 288 Startzeitpunkt der CAN-Interfaces mit \verb+modprobe+ Kernelmodule zu
 289 laden, noch bevor die automatische Ladefunktionalität durch das
 290 Öffnen eines Socket ausgeführt wird. Hintergrund: Auf sehr langsamen
 291 Systemen kann ein zeitnahes Laden nicht immer in der Art gewährleistet
 292 werden, wie es manche Protokoll-Spezifikation verlangen. Durch das
 293 Setzen der Variable \verb+PROBE="can-tp20 can-tp16"+ werden beispielsweise
 294 diese Protokollmodule im Speicher vorgehalten.\\
 295
 296 Soll das Script \verb+/etc/init.d/can_if+ beim Systemstart automatisch
 297 gestartet werden, müssen gemäß den Runleveln im SystemV Init
 298 symbolische Links gesetzt werden. Beispielsweise:\\
 299
 300 \begin{code}
 301 root@pplinux1:/# ln -sf /etc/init.d/can_if /etc/rc0.d/S35can_if
 302 root@pplinux1:/# ln -sf /etc/init.d/can_if /etc/rc6.d/S35can_if
 303 root@pplinux1:/# ln -sf /etc/init.d/can_if /etc/rcS.d/S40can_if
 304 \end{code}
 305
 306 \subsubsection{Modul Parameter der \LL-Module}
 307 \label{modparms}
 308 Bezugnehmend auf die in Kapitel \ref{autoload} vorgestellte Datei
 309 \verb+llcf+ wird hier auf die Modul-Parameter der \LL-Module
 310 eingegangen. Wurde beim Kompilieren (siehe Kapitel \ref{compile}) die
 311 Option \verb+DEBUG=-DDEBUG+ mit angegeben, kann beim Laden des Modules
 312 ein Parameter \verb+debug=<x>+ angegeben werden. Der Wert \verb+<x>+
 313 ist dabei binär kodiert und bedeutet:
 314
 315 \begin{description}
 316 \item[Bit 0 gesetzt] Debug-Ausgabe des Moduls eingeschaltet
 317 \item[Bit 1 gesetzt] Ausgabe der Socket-Buffer-Daten eingeschaltet
 318 \end{description}
 319
 320 Es ist möglich (wenn auch nicht empfehlenswert) in der Datei
 321 \verb+can+ zum Beispiel die Zeile\\
 322
 323 \verb+option can debug=1+\\
 324
 325 einzutragen. Besser ist es, mit \verb+insmod can debug=1+ das Modul
 326 einmalig zum Testen 'von Hand' zu laden. Ggf. muss es vorher allerdings
 327 mit \verb+rmmod can+ entfernt werden (siehe dazu Kapitel
 328 \ref{remove}).\\
 329
 330 Der generische Transportprotokoll-Treiber \verb+can-tpgen+ bietet die
 331 Option, sich die Statistiken einer Transportprotokollverbindung
 332 (Anzahl der Pakete, Anzahl der Bytes, Anzahl der Retries) im
 333 Kernel-Log ausgeben zu lassen. Dazu muss die Option \verb+printstats=1+
 334 gesetzt sein. Da hier nicht viele Daten anfallen, kann dieses bei
 335 Bedarf auch in der Datei \verb+llcf+ eingetragen werden.\\
 336
 337 \verb+option can-tpgen printstats=1+\\
 338
 339 \subsubsection{Entfernen von geladenen \LL-Modulen}
 340 \label{remove}
 341
 342 ACHTUNG! Zum Entfernen von geladenen \LL-Modulen müssen zunächst immer
 343 alle Applikationen, die auf das \LL\ aufsetzen, beendet und alle
 344 CAN-Interfaces heruntergefahren werden (z.B. mit
 345 \verb+/etc/init.d/can_if stop+).\\
 346
 347 In diesem Beispiel sind die CAN-Interfaces 'vcan0' und 'vcan1' noch
 348 hochgefahren, was beim Module 'vcan' zu einem Usage-Count von zwei führt.
 349
 350 \begin{code}
 351 root@pplinux1:/# lsmod
 352 Module                  Size  Used by    Tainted: P
 353 pcan                   29424   1 (autoclean)
 354 vcan                    2560   2 (autoclean)
 355 can-tp20                6692   0 (unused)
 356 can-tpgen               5368   0 [can-tp20]
 357 can-bcm                 7940   0 (unused)
 358 can-raw                 2564   0 (unused)
 359 can                    10432   0 [can-tp20 can-tpgen can-bcm can-raw]
 360 (..)
 361 \end{code}
 362
 363 Nach dem Herunterfahren der CAN-Interfaces kann man entsprechend den
 364 Abhängigkeiten die Module entfernen. Im Beispiel hängt \verb+can-tp20+ von
 365 \verb+can-tpgen+ ab und \verb+can-tp20 can-tpgen can-raw vcan+
 366 hängen von \verb+can+ ab. D.h. die Reihenfolge zum Entladen der
 367 Module ist:\\
 368
 369 \verb+rmmod can-tp20 can-tpgen can-raw vcan can+\\
 370
 371 Das kann man auch mit einzelnen \verb+rmmod+-Aufrufen
 372 realisieren. Wenn ein Modul nicht entladen werden kann, gibt es eine
 373 Fehlermeldung.