itifg(4)

NAME
itifg - ladbares Kernel-Modul (Version 0.7.1) zur Unterstützung von Frame-Grabber Karten der Firma Imaging Technology Inc.

ÜBERSICHT
insmod itifg [major=xxx]
rmmod itifg
/dev/MAKEDEV.itifg
/etc/rc.d/init.d/itifg {start|stop|restart}

BESCHREIBUNG (Hardware)
Die Firma ITI stellt unterschiedliche Bildverarbeitungskarten zum Anschluß der verschiedensten Arten von Kameras her. Eine erste Einteilung kann erfolgen in Karten zum Anschluß von analogen oder digitalen, bzw. Farb- oder Schwarz/Weiß- Kameras.
Es gibt, bedingt durch das Fortschreiten der Entwicklung im Bereich der Elektronik, bisher zwei Generationen von Bildverarbeitungskarten. Die erste Generation stellt sich in Komponentenbauweise, bestehend aus Grund- und Aufnahmemodul, dar, während die zweite Generation jeweils als Einplatinenlösung gehalten ist.

  1. Generation:
IC-PCI + AM-VS,AM-FA,AM-CLR,AM-STD,AM-DIG,AM-MTD
Das IC-PCI bildet hierbei das Grundmodul. Es ist in verschiedenen Varianten gebaut worden, wobei einerseits zwei verschiedene Platinen, aber andererseits auch drei verschiedene PCI Schnittstellenbausteine zum Einsatz kamen. Zusätzlich dazu wurden diese Varianten auch whlweise mit 2 oder 4MB VRAM bestückt.
Die zwei Platinenvarianten (gekennzeichnet alt: A...A11 / neu: B...B5) unterscheiden sich auch in Ihrer Funktionalität, wobei die neueren Varianten eine komfortable parallele Ein/Ausgabeschittstelle haben und Bildverkleinerung unterstützen. Bei den PCI Schnittstellenbausteinen ist dies etwas anders, Sie unterscheiden sich nur dahingehend, daß Sie mehr oder weniger Funktionsfehler aufweisen. Mit den Bausteinen S5933/S5933Q (verbaut auf den Platinen A...A9) arbeitet der Treiber nicht zuverlässig zusammen!

Da sich die Aufnahmemodule in Ihrer Programmierung wesentlich unterscheiden, sind die direct unterstützten mit (*), die mittels Patch anspechbaren mit (**) gekennzeichnet:

AM-VS (analog; Schwarz/Weiß) (*)
    Anschluß auch von Nicht-Standard Kameras mittels Übertragung von HSync/VSync und Pixeltakt (Variable-Scan) möglich. Dies schließt auch Zeilenkameras ein.
    Für horizontale Auflösungen > 1024 ist es auch in einer Variante mit 4k-FIFO lieferbar.

AM-FA (analog; Schwarz/Weiß)
    Gedacht für Kameras mit bis zum 50MHz Pixeltakt (Fast-Acquisition) und frei wählbaren PLL-Takten (Überabtastung möglich)

AM-CLR (analog; Farbe und Schwarz/Weiß) (**)
    Dieses Modul ist fast universell einsetzbar. Während Kameraeingang 0 oder 1 für ein RGB Farbkamerasignal ausgelegt ist, ist an Eingang 2 der Anschluß eines S-VHS, bzw. NTSC oder PAL Signales möglich. Letztendlich ist aber auch die gleichzeitige Verarbeitung von mehreren Monochromsignalen durch den 3fach- Wandler denkbar.
    Als Variante ist das Modul auch mit einem CSC (Color Space Converter) verfügbar. Mit diesem ist eine Umrechnung der verschiedenen Farbräume ineinander ohne Verzögerung möglich.
    Das Modul wird ersetzt durch den Nachfolgetyp AM-STD.

AM-STD (analog; Farbe und Schwarz/Weiß) (**)
    Eigentlich handelt es sich hierbei um zwei verschiedene (Standard-) Module.
    Das nomale STD-Modul unterstützt, wie der Name schon, sagt Standard- Monochrom- (CCIR, RS-170) und Farb- (PAL, NTSC, S-VHS) Signale.
    Beim STD-RGB handelt es sich vom Funktionsumfang her eher den AM-CLR Nachfolger. Es ist auch mit CSC lieferbar.

AM-DIG (digital; Schwarz/Weiß, teilweise auch Farbe) (*)
    Vorgesehen zum Anschluß von digitalen Flächen- und Zeilenkameras. Der Bittiefe der Kamera angepaßt gibt es 8, 16 und 24bit Ausführungen, wobei die 24bit Variante für den Anschluß von Farbkameras gedacht ist.
    Mit Blick auf die verschiedenen Arten der digitalen Datenübertragung gibt es bei der Auslegung der Eingangsschaltung TTL, RS-422 und auch RS-644 Ausführungen.

AM-MTD (digital; Schwarz/Weiß)
    Ausschließlich zum Anschluß von Zeilenkameras mit Mehrfachausgängen (bis zu 8 × 8bit).

  2. Generation:
PCVision, PCRGB, PCDig
Diese Bildverarbeitungskarten der zweiten Generation unterscheiden sich im internen Aufbau doch sehr stark. Während es sich beim PCVision noch um ein IC-PCI mit einem neuen Aufnahmemodul in Einkartenbauweise handelt, sind PCRGB und PCDig komplette Neuentwicklungen. Die herausragendste Eigenschaft ist dabei, daß beide über eine in Hardware implememtierte Lösung zum seitenweisen Transfer der Daten verfügen. Dies entlastet den Host-PC erheblich.
Auch in der folgenden Auflistung wird eine direkte Unterstützung mit (*) und eine Unterstützung mittels Patch mit (**) gekennzeichnet.

PCVision (analog; Schwarz/Weiß) (*)
    Nachfolger zum AM-VS

PCRGB (analog; Farbe und Schwarz/Weiß)
    Nachfolger zum AM-STD mit erweiterten Merkmalen des AM-FA (hohe Wandlungsfrequenz).

PCDig (digital; Farbe und Schwarz/Weiß) (*)
    Nachfolger zum AM-DIG mit erweiterten Merkmalen des AM-MTD (unterstützt Mehrfachausgänge).

Für weiterreichende Informationen kann http://www.imaging.de empfolen werden.

BESCHREIBUNG (Software)
Der vorliegende Gerätetreiber ist für einen Zugriff über die allgemeine Schnittstelle für zeichenorientierte Geräte im Linux Treibermodell spezifiziert. Somit erfolgt die grundlegende Ansteuerung über die allgemeinen Systemaufrufe wie open(2), close(2), read(2), write(2). Die erweiterten Möglichkeiten werden über ioctl(2), mmap(2), select(2) ,( poll(2) (, signal(2), fcntl(2), abgebildet.

Fuer das grundlegende Verständnis der Funktionsweise des Treibers und eine spätere detaillierte Beschreibung der Systemaufrufe soll nun als erstes ein Überblick über Grundprinzipien im Treiberaufbau gegeben werden:

  1. Datenfluß:
Als Datenquelle fungiert die angeschlossene analoge bzw. digitale Kamera. Deren Daten werden vor dem ersten open(2) und nach dem letzten close(2) generell verworfen. D.h. nur wenn wenigstens ein Prozess ein ‘Gerät für die Bildaufnahme’ (genaue Erläuterung siehe später) geöffnet hat, werden die Daten von der Kamera in den karteneigenen Speicher gelesen und dort gespeichert.
Da ein direkter Zugriff auf diesen Speicher in der Regel zu langsam ist, müssen die dort nun als Bild vorliegenden Daten noch in den Hauptspeicher des Rechners transferiert werden, was unter der direkten Kontrolle der Transferlogik auf der Bildverarbeitungskarte erfolgt (Bus Master DMA). Als Ziel dieses Transfers bieten sich nun zwei verschiedene Bereiche an, welche von der weiteren Verwendung des Bildes abhängen. Will man nur wenige Bilder abspeichern bzw. im Nachhinein Verarbeiten, bietet sich ein Aufruf von read(2) an, wobei der Zielspeicher vom Prozess allokiert wurde und somit im Nutzersegment des Rechners liegt. Ist man an einer Live - Anzeige der Bilder oder einer Verarbeitung in Echtzeit interessiert, sollte man den mmap(2) Aufruf nutzen und auf einen im Kernsegment allokierten Speicher zurückgreifen.
Eine Unterscheidung zwischen diesen beiden Betriebsarten ist überhaupt notwendig, da beide Verfahren Vor- und Nachteile haben. Der read(2) Aufruf hat eine implizite Synchronisation durch das Blockieren des Aufrufes bis zum fertigen Bild, muß aber den (mglicherweise immer verschiedenen) Speicher im Nutzersegment vor der Auslagerung schützen. Der mmap(2) Aufruf dagegen belegt einmal einen Speicherbereich im Kern für alle folgenden Bilder, ist dann aber auf zusätzliche Maßnahmen zur Synchronisation angewiesen.
Beiden Speicherbereichen ist gemeinsam, daß sie virtuell sind (physikalisch nicht zusammenhängend). Dadurch ist bedingt, daß ein Transfer immer seitenweise erfolgen muß. Das folgende Bild soll den erläuterten Sachverhalt zusammenfassen:

                     karteneigener Speicher
     |--------|    |-----------------------|     seitenweiser Transfer
     | Kamera | -> | 1 | 2 | 3 | 4 | 5 | 6 | --> ------------------|
     |--------|    |-----------------------|     über den PCI Bus  |
                                                                   ~

                                                                   ~
     1. via read(2)         |--------------------------------------|
                       MMU  |
                   virt<->phys |
                   |-|     |-| |
                   |1|--|--|2| |
                   |-|  |  |-| |
                   |2|--|--|4| |
                   |-|  |  |-| |
                   |3|--|--|3| |
                   |-|  |  |-| |
                   |4|--|--|6| |
                   |-|  |  |-| |
                   |5|--|--|1| |
                   |-|  |  |-| |
                   |6|--|--|5| |
                   |-|     |-| |
                               |
                  Nutzersegment| Kernsegment
                    (malloc)

                                                                   ~
     2. via mmap(2)                       |------------------------|
                                     MMU  |
                   virt        | virt<->phys
                   |-|         | |-|     |-|
                   |1|         | |1|--|--|2|
                   |-|         | |-|  |  |-|
                   |2|   / M \   |2|--|--|4|
                   |-|  /     \  |-|  |  |-|
                   |3| /   M   \ |3|--|--|3|
                   |-|<         >|-|  |  |-|
                   |4| \   A   / |4|--|--|6|
                   |-|  \     /  |-|  |  |-|
                   |5|   \ P /   |5|--|--|1|
                   |-|         | |-|  |  |-|
                   |6|         | |6|--|--|5|
                   |-|         | |-|     |-|
                               |
                  Nutzersegment| Kernsegment
                                  (vmalloc)

  2. Kontrollfluß:
Da der Inhalt eines neuen Bildes zum Anforderungszeitpunkt nicht sofort zur Verfügung stehen, muß eine Art Synchronisation zwischen Anwendungsprogramm und Kamera/Bildverarbeitungskarte implementiert werden.
Am einfachsten lässt sich diese Anforderung duch einen blockierenden Systemaufruf (hier read(2)) realisieren. Dabei wird der aufrufende Prozeß im Kern 'schlafen' gelegt, bis ein neues, komplettes Bild in den Speicher eingelesen wurde. Ist dies geschehen, wird der Prozeß wieder 'geweckt' und kehrt aus dem Systemaufruf mit einer entsprechenden Fehler- oder Erfolgsmeldung zurück.
Nachteil dieser einfachen Lösung ist es, daß der aufrufende Prozeß während der gesamten Bildwartezeit untätig ist und es auch nicht möglich ist, gleichzeitig auf die Bilder von mehreren Kameras (welche ja auch unsynchronisiert laufen könnten) warten kann. Glücklicherweise bietet das Betriebssystem auch einige erweiterte Möglichkeiten zur Syncronisation, namentlich signal(2), und select(2) ( poll(2) ). Diese Aufrufe sind hauptsächlich bri einer kontinuierlichen Bildaufnahme (Zugriff auf die Bilddaten mittels mmap(2)) sinnvoll. Im ersten Fall - Synchronisation mittels Signalen - zeigt dabei das eintreffen eines Signales (hier SIGIO) an, das ein neues Bild im gemappten Speicherbereich verfügbar ist. In der vorliegenden Treiberversion sind dabei noch keine weiteren Informationen (z.B. über eine vorliegende Zeitüberschreitung oder von welcher Kamera das Bild überhaupt ist) verfügbar. Geplant ist aber eine Erweiterung in Richtung siginfo(2).
Wie erwähnt ist eine weitere standardkonforme Schnittstelle zur Lösung der gegebenen Probleme select(2) ( poll(2) ). Hierbei ist es möglich auf mehrere Dateideskriptoren (und damit auch Kameras) zu warten. Zusätzlich dazu können Ausnahmeereignisse (Zeitüberschreitung bei der Bildaufnahme) bequem abgefragt werden.
Um die eben genannten Synchronisationsmechanismen auch bei einer Einzelbildaufnachme - sprich read(2) - anwenden zu können, muß hier vorher das eigentliche Blockieren verhindert werden. Danach ist es möglich, die Bildaufnahme mit einem ersten Aufruf zu starten, dann mit einem der besprochenen Mechanismen zu warten und letztendlich einen Rückgabewert mit einem erneuten Aufruf zu erfragen. Der vorliegende Mechanismus soll sich damit an asynchroner Ein-/Ausgabe aus dem POSIX-Bereich orientieren, kann aber auf Grund der fehlenden Unterstützung im Kern dafür nicht konform sein.

Wieder soll eine Darstellung das Erläuterte näher erklären:

    1. blockierend via read(2)
                               Prozeß                     Prozeß
                                  |                          |
                                  |                          |
    Nutzersegment                 |                          |
                                 \ /                         |
                               read(2)                     read(2)
                           Bildspeicher/-größe      Fehler/Erfolgswert
                                  |                          |
    ---------------------------------------------------------------------
                                  |                          |
                             Bildaufnahme                    |
      obere Hälfte          wird gestartet                   |
                                  |                          |
                       Prozeß wird unterbrochen              |
                                                             |
    Kernsegment                   .                          |
                                  .                          |
                                  .                  Prozeß läuft weiter
      untere Hälfte      'Bild fertig' Signal               / \
                             von der Kamera                  |
                                  |                          |
                                  |--------------------------|

    2. nicht blockieren via mmap(2)
         a) signal(2)                              b) select(2)
                          Speicher einblenden
                               mit mmap(2)
                                   | |
                           Bildaufnahme starten
                         mit ioctl(2) (SET_START)
                                   | |
               |-------------------| |-------------------|
               |                                         |
       Signalbehandlung                                  |
         registrieren                                    |
         mit signal(2)                                   |
               |                                         |
    |--------->|                                         |<----------------|
    |          |                                         |                 |
    |   Restzeit warten                         Ereignisse abfragen        |
    |   mit sigsupend(2)                       (warten) mit select(2)      |
    |          |                                         |                 |
    |          |----------|                  In die einzelnen Ereignisse   |
    |                     |                          verzweigen            |
    |             Signalbehandlung                       |                 |
    |                     |                   |----------|----------|      |
    |          |----------|                   |          |          |      |
    |          |                                  Bildbearbeitung          |
    |   Bildbearbeitung                    Kamera 1     ...      Kamera n  |
    |          |                              |          |          |      |
    |<---------|                              |----------|----------|      |
               |                                         |                 |
               |                                         |---------------->|
               |                                         |
               |-------------------| |-------------------|
                                   | |
                           Bildaufnahme stoppen
                         mit ioctl(2) (SET_STOP)
                                   | |
                           Speicher ausblenden
                              mit munmap(2)

BESCHREIBUNG (Schnittstelle)
Der Treiber stellt seine Funktionalität dem Nutzer über die klar definierte Schnittstelle folgender Systemaufrufe zur Verfügung. Alle folgenden Beschreibungen beziehen sich dabei auf die Geräte zum Bildeinlesen. Ausführungen zu den anderen Geräten (z.Z. nur Ein-/Ausgabekanäle) sind unter DATEIEN zu finden.

open
    /* FILLME */

close
    /* FILLME */

read
    /* FILLME */

write
    /* FILLME */

mmap
    /* FILLME */

select
    /* FILLME */

poll
    /* FILLME */

signal
    /* FILLME */

fcntl
    /* FILLME */

ioctl
    Auf Grund des Umfangs der ioctl(2) Schnittstelle wir diese in einer gesonderten Handbuchseite itifg_ioctl(2) behandelt.

DATEIEN (gerätespezifisch)
Eine Eigenart von *nix - kompatiblen Bertiebssystemen ist es, auch Geräte als spezielle Dateien darzustellen. Diese Gerätedateien befinden sich im /dev Verzeichnis und beginnen bezogen auf die behandelten Geräte mit
/dev/ic0xxx, /dev/ic1xxx, /dev/ic2xxx...
Die aufsteigende Nummer bezeichnet dabei den Index der entspechenden Bildverarbeitungskarte im PC. XXX ist ein Platzhalter für verschiedene logisch voneinander gertrennte Funktionalitäten auf diesen Karten. Zur Zeit sind ein Gerät zum einziehen der Bilder (xxx = idI) und ein Gerät zum ansprechen der Ein-/Ausgabekanäle (xx = ioP) implementiert.

Aktualisiert werden diese Dateien beim Systemstart vom Script /etc/rc.d/init.d/itifg, welches seinerseits /dev/MAKEDEV.itifg aufruft. Dies ist notwendig, da die Haupt-Gerätenummer vom System dynamisch vergeben wird. Es werden im Moment die Gerätedateien für maximal 8 (ITI_BOARDS_MAX) einzusteckende Karten angelegt. Dies entspricht auch der vom Treiber unterstützten Anzahl.

DATEIEN (Installation)
Nach dem Aufruf von make install sollten die im Baumdiagramm dargestellten Dateien erzeugt worden sein.

    / --+-- lib/modules/`kernel version`/misc/ --+-- itifg.o
        |                                        `-- itifg_g.o
        |
        +-- etc/rc.d/ --+-- init.d/ -- itifg
        |               |
        |               `-- rc[235].d/ --+-- S25itifg
        |                                `-- K15itifg
        |
        +-- bin/config_pcdig
        |
        +-- dev/ --+-- MAKEDEV.itifg
        |          |
        |          +-- ic[01234567]idI
        |          `-- ic[01234567]ioP
        |
        `-- INSTALL_PREFIX --+-- bin/ --+-- test_itifg
             '/usr/local'    |          |-- extime_itifg
                             |          |-- swtrig_itifg
                             |          `-- ioport_itifg
                             |
                             +-- man/ --+-- man1/ --+-- test_itifg.de.1
                             |          |           `-- test_itifg.1
                             |          |
                             |          `-- man4/ --+-- itifg.de.4
                             |                      |-- itifg.us.4
                             |                      |-- itifg.4
                             |                      |-- itifg_ioctl.de.4
                             |                      |-- itifg_ioctl.us.4
                             |                      `-- itifg_ioctl.4
                             |
                             +-- lib/ --+-- libiticonfig.a
                             |          `-- libiticonfig_g.a
                             |
                             +-- include/ --+-- itifgExt.h
                             |              `-- iticonfig.h
                             |
                             `-- share/ -- itifg/ --+-- conffiles/*.cam
                                                    `-- fpgafiles/*.exo

Ein Aufruf von make uninstall löscht alle aufgeführten Dateien.

BEISPIELE
Als Programmierbeispiel für die oben angegebenen Systemaufrufe bzw. Verfahrensweisen sei auf das Programm test_itifg verwiesen, welches als Sourcecode vorliegt.
Es wurde bei der Erstellung des Programms versucht, alle möglichen Ansteuerungen des Treibers zu berücksichtigen. So ist zum Beispiel eine Auswahl des Zielspeichers und dem Zugriff darauf per Option [-o read|mmap] möglich. Weiterhin kann die Synchronisation zwischen [-s signal] und [-s select|poll] umgestellt werden.
Zusätzlich dazu sind einige Hilfsprogramme zum externen Auslösen, zur Einstellung der Belichtungszeit und zum Ansprechen der Ein-/Ausgabekanäle verfügbar.

FEHLER
Als haupsächliches Problem beim Einsatz der Bildverarbeitungkarten hat sich die Revision des PCI-Ansteuerschaltkreises erwiesen. Dieser wird von der Firma AMCC hergestellt und als PCI-Matchmaker S5933 bezeichnet.
Bei den auf den Karten eingesetzten Exemplaren handelt es sich um die Versionen ohne Postfix, Q, QA - QF. Völlig fehlerfrei ist nur die Version QF, wobei die Versionen QB bis QE nur in Verbindung mit einigen Motherboard Chipsätzen Probleme bereiten. Dies drückt sich dann durch Bildfehler in Form von schwarzen Streifen in einigen Bildzeilen aus.
Sollte die Revision noch älter sein (ohne, Q oder QA) ist von einem Einsatz des Treibers abzusehen.

SIEHE AUCH
itifg_ioctl(4), test_itifg(1), insmod(1), rmmod(1), mknod(1), open(2), close(2), read(2), write(2), mmap(2), select(2), poll(2), ioctl(2), signal(2), fcntl(2)

GESCHICHTE
Folgende Personen sind beteiligt an der Entwicklung des Treibers:

Dirk Bergmann | (D.Bergmann@gom.com) | (Ansprechpartner)
Matthias Stein | (M.Stein@gom.com) | (Grundgerüst, restliche Module)
Werner Jaeger | (e9026603@student.tuwien.ac.at) | (AM-CLR)
Rin-ichiro Taniguchi | (rin@limu.is.kyushu-u.ac.jp) | (AM-STD/RGB)
Rolando Cantarutti | (rcantarutti@ctios2.ctio.noao.edu) | (AM-STD/COMP)

Der Treiber wurde haupsächlich (mit Ausnahme der Treiber für die Farbmodule) entwickelt in der

         Copyright (C) 1996-2000 GOM mbH.
    Rebenring 33, 38106 Braunschweig, GERMANY.
             Tel. ++49 531 3804-330
             Fax, ++49 531 3804-333
              All rights reserved.

Dieses Modul unterliegt der `GNU Public Licence v2.0' und ist somit auch zur kommerziellen Nutzung bei Wahrung der Lizenz freigegeben.

Die Firma GOM ist seit 1990 im Bereich der optischen Meßtechnik aktiv. Sie bietet Meßplätze (Hard- und Software) im Bereich 3D- Meßtechnik, Bildverarbeitung, Objektdigitalisierung, Reverse Engineering sowie Dehnungs- und Verformungsmessung an.

http://www.gom.com

ftp://ftp.gom.com/pub/ITI-FG/itifg-0.7.1.tar.gz,
ftp://sunsite.unc.edu/pub/Linux/kernel/misc-cards/itifg-0.7.1.tar.gz