path: root/LIESMICH

$Id: LIESMICH 1.40 2023/12/19 10:23:38 martin.burnicki REL_M $

Dies ist die LIESMICH-Datei fuer mbgtools-lx-4.2.26
---------------------------------------------------

Bitte senden Sie Anregungen und Vorschlaege an den
Meinberg Support <support@meinberg.de>


Inhalt
------
  1.   Anmerkungen und Beschreibung
  1.1  Unterstuetzte Geraete
  1.2  Unterstuetzte Linux-Versionen
  1.3  Bekannte Einschraenkungen
  2.   Treiberdateien und Programme
  3.   Installation
  3.1  Entpacken der Treiberquellen
  3.2  Ueberpruefung der Kernel-Buildumgebung
  3.3  Compilieren des Treibers
  3.4  Installation des Treibers
  3.5  Laden des Kernelmoduls
  3.6  Wenn das Kernelmodul nicht geladen werden kann ...
  3.7  Compilieren des Treibers fuer eine andere Kernel-Version
  3.8  Compilieren des Treibers fuer einen anderen Kernel-Source-Tree
  3.9  Staged Builds
  4.   Verwendung der Treibersoftware mit ntpd
  4.1  Konfiguration mit dem Shared-Memory-Treiber des ntpd
  4.2  Konfiguration mit dem Parse-Treiber des ntpd
  5.   Verwendung der Treibersoftware mit chrony
  6.   Anmerkungen zu SuSE/openSUSE Linux
  6.1  Veraltete Namen von NTP-Software-Paketen
  6.2  NTP und "Operation not permitted" unter SuSE Linux 10.1 und neuer
  6.3  Fehlermeldung "module is unsupported"
  7.   "Permission denied" mit SELinux (z.B. RedHat/Fedora/CentOS)



1. Anmerkungen und Beschreibung
-------------------------------
Dieses Treiberpaket ermoeglicht die Verwendung von PCI- und ISA-Einsteck-
karten sowie USB-Geraeten von Meinberg unter dem Betriebssystem Linux.

Die mitgelieferten Programme ermoeglichen es, die Geraete zu konfigurieren
und ihren Status zu ueberpruefen. Zusaetzlich ist es moeglich, die Geraete
als Zeitquellen fuer den bei Linux mitgelieferten NTP-Daemon (ntpd oder
chronyd) zu verwenden.

Die mitgelieferten Shared Object-Libraries ermoeglichen es, aus eigenen
Applikationen heraus direkt auf die Geraete zuzugreifen.

Mehrere unterstuetzte Geraete koennen gleichzeitig verwendet werden, und
bei entsprechender Konfiguration koennen bis zu 4 Geraete gleichzeitig
als Zeitquellen fuer den NTP-Daemon verwendet werden (dies ist eine
Linitierung des NTP-Daemon).

Wenn ein USB-Geraet als Zeitquelle fuer den NTP-Daemon verwendet wird,
muss das Geraet bereits angeschlossen sein, wenn der Daemon startet, denn
sonst wird das Geraet nicht durch den Daemon erkannt.



1.1 Unterstuetzte Geraete
-------------------------
Das Treiberpaket unterstuetzt alle PCI- und ISA-Karten sowie alle
Meinberg-USB-Geraete, die bis zur Veroeffentlichung des Pakets
eingefuehrt wurden. Meinberg achtet sorgfaeltig darauf, dass
API-Funktionen sowohl zwischen alten und neuen Geraeten als auch
alten und neuen Versionen der Treibersoftware kompatibel bleiben.



1.2 Unterstuetzte Linux-Versionen
---------------------------------
Ob das Treiberpaket mit einer bestimmten Linux-Distribution verwendet
werden kann, haengt hauptsaechlich von der Kernel-Version ab, die in der
Distribution enthalten ist, nicht jedoch von den unterschiedlichen Typen
von Distributionen wie SuSE/openSUSE, Debian/Ubuntu, RedHat/Fedora/CentOS,
usw.

Diese Version des Treibers sollte problemlos mit Linux-Kernels 2.6.x,
3.x, 4.x, 5.x und 6.x bis mindestens 6.6 funktionieren
- auf Standard-PCs (i386-Architektur)
- auf Intel/AMD-Systemen mit 64 Bit-Architektur (x86_64-Architektur)
- auf SPARC64-Architektur
- teilweise auf IA64-Architektur (Itanium)
- teilweise auf ARM-Architektur

Kernels 2.4.x und aelter werden nicht mehr unterstuetzt.



1.3 Bekannte Einschraenkungen
-----------------------------
Bei einigen Linux-Kernels wird bei Verwendung dieses Treibers ein
"tainted"-Flag im Kernel gesetzt, da ein Kernel-Modul verwendet wird,
das nicht vom Hersteller der Linux-Distribution mitgeliefert wurde.
Es wird ein entsprechender Eintrag im Syslog vorgenommen, die Funktion
des Treibers wird dadurch jedoch nicht beeintraechtigt.

Ebenso ist es moeglich, dass auf manchen Linux-Distributionen bei der
Installation mit "make install" ein Fehler

  sign-file: certs/signing_key.pem: No such file or directory

oder aehnlich ausgegeben wird, denn natuerlich koennen selbst-
compilierte Kernelmodule nicht mit dem kryptographischen Schluessel
der Linux-Distribution signiert werden.



2. Treiberdateien und Programme
-------------------------------
Das Programmpaket "mbgtools fuer Linux" basiert auf der allgemeinen,
betriebssystem-uebergreifenden Treiberbibliothek "mbglib" von
Meinberg. Auf Grundlage dieser Bibliothek wurden die folgenden
ausfuehrbaren Programme entwickelt. Zusaetzlich gibt es einige
Shared-Object-Libraries, die auch von eigenen Programmen genutzt
werden koennen, sowie ein Kernel-Modul, das den Zugriff auf die
Hardware ermoeglicht.

Der Sourcecode jedes einzelnen Programms ist in einem
Unterverzeichnis mit dem entsprechenden Namen abgelegt.

Alle auf der Kommandozeile ausfuehrbaren Programme koennen mit
einem Parameter -? oder -h aufgerufen werden, um die moeglichen
Aufrufparameter anzuzeigen.

mbgstatus
  Dieses Programm zeigt Statusinformationen eines Geraetes an.
  Die Art der Informationen haengt ab vom Typ des verwendeten
  Geraets ab. Bei Verwendung eines oder mehrerer Parameter '-v'
  werden mehr Details ausgegeben.

mbgctrl
  Dieses Programm kann verwendet werden, um einige konfigurierbare
  Parameter eines Geraetes anzupassen.

mbgirigcfg
  Dieses Programm kann verwendet werden, um die Einstellungen eines
  IRIG-Ein- oder Ausgangs zu konfigurieren, sofern das Geraet solche
  Ein- oder Ausgaenge hat.

mbgsetsystime
  Dieses Programm liest die Zeit von einem Geraet und setzt damit
  einmalig die Systemzeit des Rechners. Wenn NTP auf einem Rechner
  mit ungenauer Hardware-Uhr verwendet wird, kann das Programm
  verwendet werden, um vor dem Start des NTP-Daemons die Rechnerzeit
  zu setzen. Das Programm sollte nicht mehr aufgerufen werden, wenn
  der NTP-Daemon bereits laeuft, da die Synchronisierung der
  Systemzeit durch den NTP-Daemon durch den Aufruf nur gestoert
  wuerde.

mbgshowsignal
  Dieses Programm zeigt die Modulation (also die Sekundenimpulse)
  eines empfangenen Langwellensignals an, z.B. bei DCF77-Empfaengern.

mbggpscap
  Dieses Programm liest Capture-Ereignisse aus dem FIFO-Puffer eines
  Geraetes und zeigt sie an, wenn die Karte ueber entsprechende Eingaenge
  verfuegt. Beachten Sie bitte, dass die DIP-Schalter auf der Einsteckkarte
  entsprechend den Angaben im Handbuch der Karte korrekt eingestellt werden
  muessen, um die Time-Capture-Eingaenge zu verwenden.

mbghrtime
  Dieses Programm liest Zeitstempel mit hoher Aufloesung der Sekunden-
  Bruchteile (high-resolution time, HR time). Bitte beachten Sie, dass
  manche Einsteckkarten diese Zeitstempel gar nicht oder erst ab einer
  bestimmten Firmware-Version unterstuetzen.

mbgfasttstamp
  Dieses Beispielprogramm zeigt, wie Zeitstempel mit hoher Aufloesung
  in sehr schneller Folge von einer PCI-Karte gelesen werden koennen.
  Diese Methode kann jedoch nur angewendet werden, wenn die PCI-Karte
  Memory Mapped I/O unterstuetzt. Zum Release-Zeitpunkt dieses Treibers
  Aktuelle PCI-Karten unterstuetzen dieses Feature, aeltere Kartentypen
  und USB-Geraete jedoch nicht.

mbgxhrtime
  Dieses Beispielprogramm zeigt, wie hochaufloesende Zeitstempel
  durch Extrapolation schneller erzeugt werden koennen, als es der
  direkte Zugtriff auf die Karte zulaesst. Diese Methode ist nicht
  so einfach wie die im Programm "mbgfasttstamp" gezeigt Methode,
  dafuer funktioniert sie aber mit allen Karten, die das Auslesen
  von hochaufloesenden Zeitstempeln (HR Time) unterstuetzen, auch
  wenn eine Karte kein memory Mapped I/O unterstuetzt.
  Das Programm startet dazu einen zusaetzlichen Thread, der
  sekuendlich einen hochaufloesenden Zeitstempel von dem Geraet
  und einen zugehoerigen Cycles Count des Betriebssystems liest.
  Der aktuelle Zeitstempel wird dann durch Extrapolation mit
  Hilfe des aktuellen Cycles Count berechnet.
  Eine Einschraenkung dieses Verfahrens besteht darin, dass der
  Wert des Timestamp Counter Registers der CPU (TSC) als Cycles
  Count verwendet wird. Bei aelteren CPU-Typen oder Chipsaetzen
  des PCs koennen die verschiedenen CPUs/Cores unterschiedliche
  TSC-Werte liefern. Daher sorgt das Beispielprogramm dafuer,
  dass es immer auf demselben CPU-Core ausgefuehrt wird (CPU-
  Affinitaet). Ausserdem muss darauf geachtet werden, dass bei
  aelteren CPU-Typen die Stromspar-Mechanismen auch den TSC-Takt
  veraendern koennen, was eine fehlerhafte Extrapolation der Zeit-
  stempel zur Folge haette. Daher sollte bei solchen Systemen das
  dynamische Heruntertakten (Intel Speedstep, AMD Cool'n'Quiet)
  im BIOS-Setup ausgeschaltet werden.

mbgcmptime
  Dieses Programm liest die Zeitstempel von 2 Geraeten und zeigt
  die Zeitdifferenz an. Der Cycles Counter wird verwendet, um die
  Latenz zu kompensieren, die entsteht, weil die Geraete nur
  nacheinander ausgelesen werden koennen.

mbgtcrcal
  Das Programm kann verwendet werden, um bei Time Code Reader-Devices
  (TCR) einen Kompensationswert fuer die Signallaufzeit im Eingang zu
  zu hinterlegen.

mbgdevio, mbgutil
  Shared-Object-Libraries, die einige API-Funktionen bereitstellen,
  di auch von eigenen Programmen benutzt werden koennen, um direkt
  auf ein Geraet zuzugreifen. Details dazu finden Sie in unserer
  Knowledge Base unter
  https://kb.meinbergglobal.com/kb/driver_software/meinberg_sdks/start

mbgsvcd
  Der Meinberg Service Daemon. Muss gestartet werden, um Zeitstempel
  von den installierten Geraeten zu lesen und diese in den Shared
  Memory-Bereich des NTP-Daemon zuschreiben. Auf diese Weise wird
  eine bessere Zeitgenauigkeit erreicht als mit der frueher
  werwendeten Methode. Siehe auch Abschnitt 4.1.

mbgclock.ko
  Ein Kernelmodul, welches den eigentlichen Treiber implementiert.


3. Installation
---------------
Das Treiberpaket kann von einem Readonly-Git-Repo mit dieser URL
geklont und spaeter einfach aktualisiert werden:
https://git.meinbergglobal.com/drivers/mbgtools-lx.git

Von diesem git-Repo koennen auch beliebige Version als zip-
oder .tar.gz-Archiv heruntergeladen werden.

Die aktuelle Release-Version steht auch auf der Meinberg-
Software-Downloadseite zur Verfuegung und ist auf dem USB-Stick
enthalten, der im Lieferumfang der Geraete enthalten ist.


3.1 Entpacken der Treiberquellen
--------------------------------
Wenn der Treiber als .tar.gz-Archiv vorliegt, kann dieses mit
Hilfe des folgenden Befehls entpackt werden:

  tar xvzf mbgtools-lx*.tar.gz

Nachdem die Dateien entpackt wurden, wechseln Sie in das neu
angelegte Verzeichnis, das beim auspacken angelegt wurde.

Um das Treiberpaket als git-Repo zu klonen, koennnen Sie
folgenden Befehl ausfuehren:

  git clone https://git.meinbergglobal.com/drivers/mbgtools-lx.git

Dadurch wird ein neues Verzeichnis mbgtools-lx angelegt, in das
Sie vor weiteren Arbeitsschritten wechseln muessen. Anschliessend
kann beliebig oft das Kommando

  git pull

ausgefuehrt werden, um das Paket auf die neueste Version zu
aktualisieren. Ebenfalls koennen dann beliebige Branches oder
Versionen ausgecheckt werden, wie es bei der Arbeit mit git
ueblich ist.


3.2 Ueberpruefung der Kernel-Buildumgebung
------------------------------------------
Da das Kerneltreiber-Modul direkt in den Kernel geladen wird, ist es
SEHR wichtig, dass das Treibermodul mit den gleichen Konfigurationsparametern
compiliert wird wie der laufende Kernel. Aus diesem Grund muessen die
Kernelquellen bzw. die sogenannten Kernel-Headers installiert sein.

Unter Debian/Ubuntu koennen die Kernel-Sourcen mit Hilfe der folgenden Befehle
installiert werden:

  apt-get install linux-headers-$(uname -r)
  apt-get build-dep linux-headers-$(uname -r)

-oder-, wenn dies nicht unterstuetzt wird:

  sudo apt-get install linux-headers-generic
  sudo apt-get build-dep linux-headers-generic


Unter Fedora/Redhat/CentOS muss das RPM-Paket "kernel-devel" und
eventuell "kernel-headers" installiert werden, sowie der Compiler
und das "make"-Programm:

  sudo dnf install kernel-devel-$(uname -r) gcc make

-oder-, wenn der Paketmanager dnf noch nicht unterstuetzt wird:

  sudo yum install kernel-devel-$(uname -r) gcc make


Unter SuSE/openSUSE heisst das zu installierende RPM-Paket "kernel-devel"
oder "kernel-default-devel" z.B. unter SLES11 SP2. Aufgrund von
Paketabhaengigkeiten wird oft der ganze Kernel-Source-Paket installiert,
z.B. "kernel-source" or "kernel-default-source". Zusaetzlich muss das
gcc-Compiler-Paket sowie "make" installiert werden:

  sudo zypper in kernel-devel gcc make

Auf *sehr* alten SuSE-Systemen ist das "zypper"-Kommando noch nicht
verfuegbar. Zum Beispiel fuer SuSE 9.1 sind die Pakete "kernel-source",
"kernel-syms" sowie "gcc" und "make" erforderlich und koennen ueber das
Konfigurationsprogramm "yast" installiert werden.


Unter arch Linux muss das Paket "linux-headers" installiert werden:

  sudo pacman -S linux-headers


ACHTUNG:

Es ist sehr wichtig, dass eine Version der Kernel-Headers installiert
ist, die zur Version des laufenden Kernels passt. Fehler beim
Compilieren des Kernel-Moduls koennen sonst z.B. auftreten

  - wenn eine neuere Version des Kernels bereits als Online-Update
    verfuegbar ist, aber noch nicht installiert wurde

  - wenn eine neuere Version des Kernels bereits installiert wurde,
    aber das System noch nicht neu gebootet wurde, so dass aktuell
    noch ein aelterer Kernel ausgefuehrt wird.

In einem solchen Fall ist es moeglich, dass die gerade installierten
Kernel-Headers eine andere Version haben als der laufende Kernel.
Der Paket-Manager der Linux-Distribution kann verwendet werden, um
zu pruefen, ob eine Version der Kernel-Headers existiert, die
mit der Version des laufenden Kernels und damit der Ausgabe des
Befehls "uname -r" uebereinstimmt.


Anders als bei aelteren Versionen des Linux-Kernels muessen die Kernel-
Sourcen ab 2.6 aufwaerts *nicht mehr* konfiguriert werden, denn die
Konfigurationsdateien fuer die unterschiedlichen Varianten des Kernels
werden in den entsprechenden Paketen mitgeliefert.

Wenn ein Kernelmodul auf einem System geladen wird, welches nicht exakt
den Kernelquellen entspricht, die beim Compilieren verwendet wurden,
besteht eine hohe Wahrscheinlichkeit, dass das System abstuerzt, falls
sich das Modul ueberhaupt laden laesst. Um dies zu verhindern, kann
die Build-Umgebung fuer Kernel-Module eine strenge Versionspruefung
durchfuehren. Dazu muss eine Datei mit Symbol-Versionsinformationen
des Kernels vorhanden sein, die normalerweise ebenfalls in den Paketen
mit den Kernel-Sourcen oder -Headers enthalten ist.


Es ist auch moeglich, dieses Treiberpaket auf einem Rasberry Pi mit
RaspBian Linux zu verwenden, aber es ist etwas umstaendlich, die
Build-Umgebung auf diesem System richtig einzurichten. Detailliertere
Hinweise dazu Finden Sie in unserer Knowledge Base unter
https://kb.meinbergglobal.com/kb/driver_software/driver_software_for_linux/linux_driver_package_on_raspberry_pi
oder kontaktieren Sie den Meinberg-Support (techsupport@meinberg.de),
um weitere Informationen zu erhalten.



3.3 Compilieren des Treibers
----------------------------
Stellen Sie sicher, dass das Basisverzeichnis des entpackten
Treiberpaketes das aktuelle Arbeitsverzeichnis ist. Falls der
Treiber vorher bereits compiliert wurde, sollte zunaechst

  make clean

eingegeben werden, um vorher erzeugte Dateien zu loeschen. Anschliessend
kann einfach

  make

eingegeben werden, um die Programme zu compilieren. Zunaechst werden alle
Hilfsprogramme compiliert, zum Schluss dann das Kernelmodul.

Bei bestimmten Versionen bestimmter Linux-Distributionen koennen
beim Compilieren des Kernel-Moduls Fehler auftreten, wenn die
Distribution generell mit einem aelteren Kernel geliefert wird,
aber die Maintainer der Distribution Aenderungen aus einer neueren
Kernelversion zurueckportiert haben in den aelteren Kernel.

Es ist oft schwierig, solche Aenderungen automatisch zu erkennen,
aber dieses Treiberpaket enthaelt Workarounds fuer einige solcher
Faelle. Zum Beispiel unter RHEL/CentOS 5.5 koennen Compilierfehler
auftreten mit Fehlermeldungen wie

  Fehler: Redefinition des typedef "bool"
  Fehler: Redeklaration von Aufzaehlung "false"
  Fehler: Redeklaration von Aufzaehlung "true"

bzw. auf Englisch

  error: redefinition of typedef 'bool'
  error: redeclaration of enumerator 'false'
  error: redeclaration of enumerator 'true'

Dieser Fehler kann leicht vermieden werden, indem "make" mit speziellen
Parametern aufgerufen wird, z.B.

  make KERNEL_HAS_BOOL=1 KERNEL_HAS_TRUE_FALSE=1

statt des einfachen "make" Befehls. Wenn an dieser Stelle andere
Fehler oder Warnungen angezeigt werden, kontaktieren Sie bitte
den Meinberg Support.


Im Normalfall sollte am Ende eine Meldung aehnlich wie diese
angezeigt werden:


  Build completed successfully. Now type

    make install

  to install the executable files.



3.4 Installation des Treibers
-----------------------------
Die Installation muss als Administrator "root" durchgefuehrt werden.
Wenn der aktuelle Benutzer keine entsprechenden Berechtigungen hat,
wird zur Eingabe des erforderlichen Passworts aufgefordert.
Geben Sie den Befehl

  make install

ein, um die ausfuehrbaren Programme in ihre Zielverzeichnisse
zu kopieren. Programme, die nur lesend auf die Karte zugreifen,
sind fuer jeden Benutzer ausfuehrbar und werden in das
Verzeichnis /usr/local/bin kopiert.

Programme, die die Konfiguration der Karte aendern, benoetigen
auch zur Ausfuehrung erweiterte Rechte und werden deshalb in
das Verzeichnis /usr/local/sbin kopiert.

Bitte beachten Sie auch die Hinweise in Abschnitt 1.3, wenn bei der
Installation eine Fehlermeldung ausgegeben werden sollte.

Durch Eingabe des Befehls

  make uninstall

koennen die compilierten Programme wieder entfernt werden.



3.5 Laden des Kernelmoduls
--------------------------
Nach der Installation kann das Kernelmodul erstmalig geladen werden.
Dazu wird folgender Befehl verwendet:

  modprobe mbgclock [io=<port>] [irq=<n>]

Die optionalen Kommandozeilenparameter sind *nur* fuer sehr alte
ISA-Einsteckkarten erforderlich:

  io=<port>    Die Port-Basisadresse <port> einer ISA-Karte. Die Standard-
               Einstellung ist io=0x300, es sei denn, die Einstellungen
               der DIP-Schalter bzw. Jumper der Karte wurden geaendert.

  irq=<n>      Die IRQ-Nummer <n> einer ISA-Karte entsprechend der Einstellung
               des DIP-Schalters bzw. Jumpers auf der Karte. Die Standard-
               Einstellung der Karten ist "kein Interrupt".

Fuer PCI-Karten koennen diese Parameter automatisch ermittelt werden, und
fuer USB-Geraete werden sie gar nicht benoetigt.

Wenn das Modul "mbgclock" geladen wird, werden einige Startmeldungen
erzeugt, die man mit dem Befehl "dmesg" ansehen kann. Die Meldungen werden
aber auch in das Syslog geschrieben. Nach dem Laden sollte das Modul mit
aufgelistet werden, wenn der Befehl

  lsmod

ausgefuehrt wird. Nun koennen Sie den Status der Funkuhr anzeigen
durch Eingabe von

  mbgstatus

Die Ausgabe des Programms zeigt je nach Art der Einsteckkarte
unterschiedliche Statusinformationen.

Nachdem das Kernelmodul einmalig manuell geladen wurde, "kennt" das
Betriebssystem die PCI-Karten und USB-Geraete, die durch das Modul
unterstuetzt werden und sollte zukuenftig das Modul automatisch
laden, wenn eine unterstuetzte PCI-Karte installiert ist oder ein
unterstuetztes USB-Geraet angeschlossen wird.

Die mitinstallierten udev-Regeln sorgen dafuer, dass fuer jedes Geraet
ein Geraete-Eintrag (Device Node) sowie ein "refclock"-Link zur
Verwendung mit NTP angelegt werden. Die Udev-Regeln sind in
folgender Datei zu finden:
/etc/udev/rules.d/55-mbgclock.rules

Wenn eine aeltere Udev-Version installiert ist oder eine ISA-Karte
verwendet wird, wird das Kernelmodul eventuell nicht automatisch
geladen. In diesem Fall kann der Befehl

  modprobe mbgclock

gegebenenfalls mit Parametern wie oben beschrieben in eine der
Script-Dateien eingetragen werden, die beim Start des Betriebssystems
ausgefuehrt werden, z.B. in die Datei /etc/init.d/boot.local auf
SuSE/openSUSE-Systemen.

Wenn das Modul geladen wird, werden auch fuer ISA-Karten die
entsprechenden Device Nodes automatisch angelegt.



3.6 Wenn das Kernelmodul nicht geladen werden kann ...
------------------------------------------------------
Wenn das Kernelmodul nicht geladen werden kann, ist meist die Kernel-
Buildumgebung nicht korrekt aufgesetzt.

Der Grund dafuer kann sein, dass der Kernel nach der urspruenglichen
Systeminstallation aktualisiert wurde, die Kernelquellen jedoch nicht.

Bei RPM-basierenden Linux-Distributionen kann dies passieren, wenn
der Kernel ueber ein Online-Update aktualisiert wurde, die Kernelquellen
jedoch von den Original-Medien (CDROM oder DVD) nachinstalliert werden.

Unter Debian/Ubuntu sind Faelle aufgetreten, in denen die Kernel-
Entwicklungsumgebung auf den ersten Blick korrekt augesetzt zu sein
schien, aber bei Eingabe des Befehle "modprobe mbgclock" der Fehler
ausgegeben wurde

FATAL: Module mbgclock not found.

obwohl vorher "make install" ohne Fehler ausgefuehrt wurde. In diesen
Faellen war das Kernelmodul fuer eine andere Kernelversion als die
laufende compiliert und installiert worden. Eine entsprechende
Ueberpruefung kann durch den folgenden Befehl durchgefuehrt werden:

# find /lib/modules/ -name mbgclock.ko; uname -r
/lib/modules/2.6.27-7-generic/extra/mbgclock.ko
2.6.27-7-generic

Wenn die Versionskennung in den zwei ausgegebenen Zeilen oben nicht
genau uebereinstimmt, passen die Kernelquellen nicht zum aktuell
laufenden Kernel.

Mit Hilfe der Paketmanagement-Software (s.B. Synaptic) koennen die
installierten und verfuegbaren Versionen sowohl des Kernels
(linux-image-generic) als auch der Kernelquellen (linux-headers-generic)
ueberprueft werden. Synaptic bezeichnet die angegebenen Pakete als
Meta-Pakete, die auf die korrekten, zusammenpassenden Versionen verweisen.

Die Kernel-Header sollten deinstalliert werden, anschliessend koennen
optional Updates installiert werden, und zum Schluss werden die
Kernel-Header neu in der passenden Version installiert.



3.7 Compilieren des Treibers fuer eine andere Kernel-Version
------------------------------------------------------------
Normalerweise wird auf das Kernel-Buildsystem wie ueblich
ueber die Verzeichnisse

/lib/modules/$(TARGET_KERNEL)/source
/lib/modules/$(TARGET_KERNEL)/build

zugegriffen, und der Ausdruck $(TARGET_KERNEL) wird fuer das
laufende System durch durch den Text ersetzt, den der Befehl
"uname -r" ausgibt.

Um den Treiber fuer ein anderes Zielsystem mit anderer Kernel-Version
zu compilieren, kann beim Aufruf von "make" die Version des Target-Kernels
angegeben werden, wie sie beim Aufruf von "uname -r" auf dem Zielsystem
angezeigt wird, z.B.:

  TARGET_KERNEL=2.6.17 make

Natuerlich muessen die entsprechenden Kernel-Sourcen vorhanden und
passend fuer den Ziel-Kernel konfiguriert worden sein.

Das compilierte Modul muss gegebenenfalls manuell auf das Zielsystem
kopiert werden.



3.8 Compilieren des Treibers fuer einen anderen Kernel-Source-Tree
------------------------------------------------------------------
Wenn der Kernel-Treiber fuer einen komplett anderen Kernel compiliert
werden soll, der nicht ueber die im vorherigen Abschnitt angegebenen
Pfade erreichbar ist, kann auch der vollstaendige Pfad zu den zu
verwendenden Kernelquellen angegeben werden, z.B.:

  BUILD_DIR=/usr/src/linux-3.16.7-53 make

Zu beachten ist, dass die Kernelquellen bereits fuer ein bestimmtes
System konfiguriert sein muessen, und dass das compilierte Kernelmodul nur
auf einem System geladen werden kann und darf, auf dem der entsprechende
Kernel ausgefuehrt wird.



3.9 Staged Builds
-----------------
Ein "Staged Build" bedeutet, dass ein Paket auf einem Build-System so
kompiliert wird, dass es auf einem anderen Zielsystem lauffaehig ist.

Anstatt auf dem Build-System installiert zu werden, werden die kompilierten
Binaerdateien normalerweise nur in einem lokalen Ausgabeverzeichnis
installiert, von wo aus sie spaeter auf das Zielsystem kopiert werden.

Nuetzliche Umgebungsvariablen fuer Staged Builds:

STAGED_BUILD: Wenn definiert, werden einige Systempruefungen uebersprungen
und es sind keine root-Rechte fuer die Installation erforderlich, da die
Installation in lokale Unterverzeichnisse ergolgt, die ebenfalls definiert
werden muessen.

INSTALL_MOD_PATH: Das Ausgabeverzeichnis, in das der Kerneltreiber
installiert wird.

DESTDIR: Das Verzeichnis, in dem die User-Space-Dateien installiert werden.
prefix:  Praefix fuer das 'bin'-Verzeichnis, z.B. '/usr' statt '/usr/local'.

DONT_BUILD_USERSPACE: Falls definiert, nur den Kernel-Treiber erstellen
bzw. installieren.

DONT_BUILD_DRIVER: Wenn definiert, werden nur die User-Space-Dateien
erstellt bzw. installiert.

BUILD_DIR: sollte wie im vorherigen Kapitel erlaeutert auf den
konfigurierten Kernel-Source-Tree.


Die fruehere Makefile-Variable "CALLED_FROM_SPEC" heisst jetzt "STAGED_BUILD".
Aus Gruenden der Abwaertskompatibilitaet wird jedoch ein Alias
"CALLED_FROM_SPEC" bereitgestellt.



4. Verwendung der Treibersoftware mit ntpd
------------------------------------------
Dieses Treiberpaket kann auf 2 unterschiedliche Arten dem NTP-Daemon
die Zeit von einer Einsteckkarte oder einem USB-Geraet bereitstellen.

In beiden Faellen muss die Datei ntp.conf editiert werden, um den
NTP-Daemon entsprechend zu konfigurieren.

Grundsaetzliche Informationen, wie Meinberg-Funkuhren mit NTP verwendet
werden koennen, gibt es auf dieser webseite:
http://www.meinberg.de/german/info/ntp.htm

Der aktuelle NTP-Sourcecode ist hier verfuegbar:
http://support.ntp.org

Normalerweise ist der NTP-Sourcecode auch als Paket der Linux-
Distribution verfuegbar.



4.1 Konfiguration mit dem Shared-Memory-Treiber des ntpd
--------------------------------------------------------
Diese Verwendungsweise des Treibers mit ntpd lieferte die bestmoegliche
Zeitgenauigkeit und sollte daher vorzugsweise verwendet werden.

Das Treiberpaket enthaelt einen zusaetzlichen Dienst "mbgsvcd"
(Meinberg Service Daemon), der sekuendlich den Kernel-Treiber aufruft,
damit dieser sowohl die Zeit von der PCI-Karte oder dem USB-Geraet als
auch die aktuelle Systemzeit moeglichst schnell hintereinander liest.

Die zurueckgelieferten Zeitstempel werden ueber den Shared Memory-Bereich
des ntpd an diesen uebermittelt. Diese Vorgehensweise vermeidet
Interrupt-Latenzen und Verarbeitungszeiten, die bei Verwendung des
Parse-Treibers auftreten (siehe naechster Abschnitt).

Falls bereits eine fruehere Konfiguration fuer den Parse-Treiber (Typ 8)
in ntp.conf existiert, z.B. Zeilen wie

server 127.127.8.<n>  mode 2
...

dann sollten zunaechst diese Zeile und alle anderen Zeilen, die sich
auf die gleiche Adresse 127.127.8.<n> beziehen, entfernt werden. Der
Parse-Treiber unterstuetzt bis zu 4 Geraete, daher koennen gegebenenfalls
mehrere solcher Abschnitte mit Werten von 0 bis 3 fuer <n> vorhanden sein.
Diese sollten alle entfernt werden.

Auch der NTP-Shared Memory-Treiber unterstuetzt bis zu 4 Geraete mit
Index 0 bis 3.

Daher sollten fuer jedes einzelne Geraet jeweils alle folgenden Zeilen
in ntp.conf eingetragen werden, um ntpd mitzuteilen, dass er
die Referenzzeit ueber den Shared Memory-Treiber (Typ 28) mit Index <n>
lesen soll:

server 127.127.28.<n> minpoll 4 maxpoll 4 iburst
fudge 127.127.28.<n> refid GPSs

Der Wert fuer "refid" ist rein informativ und kann auf beliebige
Zeichenketten mit bis zu 4 Buchstaben gesetzt werden. Im Beispiel oben
wurde "GPSs" verwendet, um anzuzeigen, dass es sich um eine GPS-Zeitquelle
handelt ("GPS"), die ueber den Shared Memory-Treiber ("s") angesprochen
wird. Als Empfehlung koennten je nach verwendeter Einsteckkarte folgende
Bezeichnungen verwendet werden:

  GPS-Karte      refid GPSs
  DCF77-Karte    refid DCFs
  TCR-Karte      refid TCRs
  PTP-Karte      refid PTPs

Nachdem die Konfiguration abgeschlossen ist, sollte der NTP-Daemon
(neu) gestartet werden. Aber auch der Dienst "mbgsvcd" muss dann
aktiv sein, um den ntpd mit der Referenzzeit zu versorgen.
Durch einfache Eingabe von "mbgsvcd" kann der Dienst gestartet werden,
falls das nicht schon bei der Installation geschehen ist.

Es sollte sichergestellt sein, dass *beide* Dienste (ntpd und mbgsvcd)
beim Booten automatisch gestartet werden.

Wenn die PCI-Karte oder das USB-Geraet sich mit seiner Zeitwquelle
synchronisiert hat und beide Dienste einige Minuten laufen, sollte
das Kommando "ntpq -p" eine Ausgabe wie diese erzeugen:

# ntpq -p
     remote       refid   st t when poll reach   delay   offset  jitter
=======================================================================
*SHM(0)          .GPSs.    0 l    3   16  377    0.000    0.002   0.003

Die tatsaechlich erreichbare Genauigkeit (offset and jitter) haengt
allerdings auch von der PC-Hardware, dem verwendeten Kernel usw. ab.



4.2 Konfiguration mit dem Parse-Treiber des ntpd
------------------------------------------------
Die Verwendung des Parse-Treibers (Typ 8) wurde von allen frueheren
Versionen des Treiberpaketes unterstuetzt und kann auch weiterhin
verwendet werden.

Dieser Ansatz verwendet Interrupts, aber die Interrupt-Latenzen
reduzieren die erreichbare Genauigkeit der Systemzeit, daher sollte
vorzugsweise die Konfiguration mit dem Shared-Memory-Treiber verwendet
werden, wie im vorherigen Abschnitt beschrieben.

Bei Verwendung des Parse-Treibers spricht ntpd Funkuhren von
Meinberg als Device /dev/refclock-<n> an, wobei <n> ein Index im
Bereich 0 bis 3 ist. Auf aktuellen Systemen werden symbolische
Links fuer bis zu 4 Geraete automatisch angelegt.

Achten Sie darauf, dass die Datei ntp.conf (normalerweise im Verzeichnis /etc)
einen Eintrag fuer refclock-<n> enthaelt. Die Zeilen sollten etwa so aussehen:

  server 127.127.8.<n> mode 2             # mode 2 for all Meinberg PCI cards
  fudge 127.127.8.<n> time1 0.0           # no systematic delay
  fudge 127.127.8.<n> refid GPSi          # informational, depending on card type
  fudge 127.127.8.<n> flag1 1 time2 7200  # optionally, set trust time

Dabei entspricht <n> der Index-Nummer, die auch fuer den symbolischen Link
verwendet wurde. "mode 2" gibt an, dass der NTP-Daemon das Datenformat des
Meinberg Standard-Zeittelegramms verwenden soll.

Mit Hilfe der Zeilen "fudge" werden einige NTP-Parameter fuer die Funkuhr
angepasst. Der "time1"-Parameter dient zur Kompensation einer konstanten
Verzoegerungszeit, die in diesem Fall 0 ist. Der Parameter "refid" bezeichnet
eine Zeichenkette von bis zu 4 Zeichen, die z.B. auch in der Ausgabe des
Programms "ntpq" verwendet wird. Als Empfehlung sollten je nach verwendeter
Einsteckkarte folgende Bezeichnungen verwendet werden:

  GPS-Karte      refid GPSi
  DCF77-Karte    refid DCFi
  TCR-Karte      refid TCRi
  PTP-Karte      refid PTPi

Mit Hilfe der Zeile "flag1 1 time2 7200" kann die Trust-Time fuer die Karte
eingestellt werden, d.h. das Zeitintervall, fuer das die Karte noch als
Referenzzeitquelle verwendet werden soll, wenn sie bereits synchron war, dann
aber z.B. das Zeitsignal ausbleibt und die Karte daher weiter frei laeuft.

Da der Oszillator auf einer PCI-Karte meist besser ist als der Oszillator
auf dem Mainboard des PCs, kann es je nach Anwendung durchaus sinnvoll sein,
die Karte selbst im Freilauf noch weiterhin eine bestimmte Zeit lang als
Zeitquelle zu verwenden.

Wenn die Trust-Time nicht explizit per fudge angegeben wird, wird als
Standardwert 30 Minuten verwendet. Im Beispiel oben wird der Wert auf 2 Stunden
(7200 Sekunden) eingestellt.


Der NTP-Daemon sollte nun neu gestartet werden und die NTP-Startmeldungen
im Syslog sollten auf Fehlermeldungen ueberprueft werden.

Falls im Syslog eine Meldung erscheint, der NTP-Daemon sei "unable to handle
127.127.8.<n>", so wurde der laufende NTP-Daemon ohne Unterstuetzung fuer
Funkuhren von Meinberg compiliert. In diesem Fall muss das NTP-Paket neu
compiliert werden. Die bei den meistverwendeten Distributionen mitgelieferten
NTP-Versionen koennen direkt verwendet werden.
Eine Alternative ist der Versuch, den Shared Memory-Treiber zu verwenden
wie weiter oben beschrieben.



5. Verwendung der Treibersoftware mit chrony
--------------------------------------------
Chrony ist eine alternative Implementierung eines NTP Daemons, die das
gleiche Shared Memory (SHM) Interface verwendet wie ntpd.
Daher kann mbgsvcd auch mit chrony verwendet werden, um die Zeit in das
Shared Memory-Segment zu schreiben.

Um chrony zu konfigurieren, dass er die Referenzzeit aus dem Shared
Memory-Segment liest, muss die folgende Zeile in der Date chrony.conf
vorhanden sein:

refclock SHM 0 poll 3 refid MBG

### Anmerkung:
Diese Konfiguration wurde noch nicht durch Meinberg getestet.
Gegebenenfalls muss ebenfalls diese Zeile in chrony.conf vorhanden sein:

server 127.127.1.1 iburst

Bitte beachten Sie, dass nur der Shared-Memory-Treiber mit chrony
verwendet werden kann. Der PARSE-Treiber des ntpd wird nicht von
chrony unterstuetzt.



6. Anmerkungen zu SuSE/openSUSE Linux
-------------------------------------

6.1 Veraltete Namen von NTP-Software-Paketen
--------------------------------------------
Aktuelle Versionen des NTP-Daemons (v4.x) heissen ntpd, waehrend aeltere
Versionen (v3.x) des Programms den Namen xntpd trugen. Bis einschliesslich
SuSE Linux 9.3 heisst das Script zum Starten und Beenden des NTP-Daemons
noch rcxntpd, obwohl das eigentliche ausfuehrbare Programm ntpd heisst.
Ab SuSE Linux 10.0 wurde das Script umbenannt in rcntp.



6.2 NTP und "Operation not permitted" unter SuSE Linux 10.1 und neuer
---------------------------------------------------------------------
SuSE Linux 10.1 wird standardmaessig mit aktiviertem AppArmor-Tool installiert,
welches die Zugriffe von Applikationen auf Dateien und Ressourcen ueberwacht und
gegebenenfalls einschraenkt.

Wenn der NTP-Daemons beim Start bzw. beim Oeffnen des Devices /dev/refclock-0
eine Fehlermeldung "Operation not permitted" ins Syslog schreibt, ist meist der
AppArmor gestartet, aber nicht konfiguriert, den Zugriff auf das Device zuzulassen.

Um den Zugriff zu erlauben, kann mit Hilfe eines Texteditors die Datei
  /etc/apparmor.d/usr.sbin.ntpd
bearbeitet werden und die Zeile
  /dev/mbg* rwl,
am Ende des vorhandenen Konfigurationsblocks eingefuegt werden.

Alternativ kann dazu statt des Texteditors auch das entsprechende Yast-Modul
verwendet werden.

Wenn der NTP-Daemon konfiguriert wird, Log-Dateien zu erzeugen, muessen auch fuer
diese Dateien entsprechende AppArmor-Eintraege hinzugefuegt werden.

Um AppArmor zu beenden, kann der Befehl

  rcapparmor stop

eingegeben werden. Ueber das entsprechende YaST-Modul kann AppArmor dauerhaft
abgeschaltet werden.



6.3 Fehlermeldung "module is unsupported"
-----------------------------------------

Wenn der Befehl "modprobe mbgclock" z.B. unter SLES11 SP2 ausgefuehrt wird,
wird folgender Fehler angezeigt:

  FATAL: module '/lib/modules/3.0.13-0.27-default/extra/mbgclock.ko' is unsupported
  Use --allow-unsupported or set allow_unsupported_modules to 1 in
  /etc/modprobe.d/unsupported-modules

Als schnelle Loesung kann also das Kommando

  modprobe --allow-unsupported mbgclock

verwendet werden, um das Kernelmodul zu laden. Um jedoch das Modul automatisch
beim Booten laden zu koennen, muss die Datei /etc/modprobe.d/unsupported-modules
editiert werden, wie in der Fehlermeldung oben angegeben.



7. "Permission denied" mit SELinux (z.B. RedHat/Fedora/CentOS)
----------------------------------------------------------------
RedHat Linux sowie auf RedHat basierende Distributionen wie Fedora und CentOS
verwenden oft SELinux, um den Zugriff von Programmen auf Dateien oder Geraete
zu beschraenken. Wenn ein neues Geraet hinzugefuegt wird, wird dem NTP-Daemon
standardmaessig der Zugriff auf das Geraet verweigert. Hinweise, wie der
Zugriff freigegeben werden kann, finden sich in der README-Datei im
Unterverzeichnis SELinux.