itifg_ioctl(4)

NAME
itifg_ioctl - unterstützte Ioctl Aufrufe zum itifg(4) Gerätetreiber

ÜBERSICHT
GIOC|HIOC _ GE|CR|VS|DG|PV|PCD _ GET|SET _ ...

BESCHREIBUNG
Um einen der im Folgenden beschriebenen ioctl(2) - Aufrufe nutzen zu können, muß die Datei INSTALL_PREFIX/include/itifgExt.h verwandt werden.
Die Notwendigkeit einer systemweit eindeutigen Kodierung der Aufrufnummer wurde erreicht, indem alle Kommandos mit dem Buchstaben ‘G /’ ‘H’ kodiert wurden, was der Präfix GIOC|HIOC zum Ausdruck bringen soll. Die nachfolgende Buchstabenkombination bezieht sich auf die zu Grunde liegende Hardware:

VS | AM-VS
DG | AM-DIG
CLR | AM-CLR
RGB | AM-STD/RGB
CMP | AM-STD/COMP
PV | PCVision
PCD | PCDig
CR | Hardware allgemein
GE | Software allgemein

Daran anschließend wird die Richtung des Datentransfers spezifiziert: GET (auslesen) und SET (setzen). Letztendlich folgt eine Abkürzung der auszulösenden Operation.
Es folgt nun eine Aufstellung der verschieden Aufrufe nach Gruppen sortiert. Zur letzten Treiberversion hinzugekommene oder geänderte ioctl's sind mit (!) gekennzeichnet.

  Hardware allgemein

GIOC_CR_SET_STOP (!)
    Die kontinuierliche Bildaufnahme in den mit mmap(2) eingeblendeten Speicherbereich wird angehalten.

GIOC_CR_SET_START (!)
    Es wird eine kontinuierliche Bildaufnahme initiiert. Zum Zugriff auf die Bilder muß vorher eine mmap(2) Operation auf der Gerätedatei (siehe auch itifg(4) DATEIEN) erfolgen.

GIOC_CR_SET_TRIG (!)
    Der Software-Trigger wird ausgelöst.
    Die Funktion dieses Aufrufs kann sofort mit dem swtrig_itifg und einer angepaßten Konfigurationsdatei getestet werden.

GIOC_CR_SET_HDEC|VDEC (!)
    Bei entsprechend ausgestattetem Grundmodul (IC-PCI ab Rev. B) kann der Grad der Verkleinerung des Bildes gewählt werden. Möglich sind (begrenzt durch die Hardware) nur Werte von 1, 2, 4, 8 - wobei die Bildzeilenlänge entsprechend gewählt werden muß. Unterstützt die Schaltung der BV-Karte diesen Modus nicht, kann nur eine Verkleinerung von 1 spezifiziert werden.

  AM-VS/PCVision spezifisch

GIOC|HIOC_VS|PV_GET|SET_LUT
    Die Lookup-Tabelle des AM-VS/PCVision wird ausgelesen/gesetzt (256Byte).

GIOC|HIOC_[VS|PV]_SET_LUT_LIN
    Die Lookup-Tabelle des AM-VS/PCVision wird linearisiert (keine Transformation).

GIOC|HIOC_VS|PV_GET|SET_NREF
    Auslesen/Setzen der negativen Referenzspannung des A/D-Wandlers. Ein Wert von 0 bis 255 entspricht einer Spannung von 0 bis 1200 mV.

GIOC|HIOC_VS|PV_GET|SET_PREF
    Auslesen/Setzen der positiven Referenzspannung des A/D-Wandlers. Ein Wert von 0 bis 255 entspricht einer Spannung von 0 bis 2000 mV.

  AM-DIG/PCDig gemeinsam

GIOC|HIOC_DG|PCD_GET|SET_LUT*PG
    Wenn man ein 16bit AM-DIG/PCDig im 8/10/12bit Modus betreibt, kann man dank der 16bit breiten Lookup-Tabelle 256/64/16 verschiedene LUT-Seiten betreiben. Mit diesem Aufruf liest/setzt man die entsprechend aktive Seite. Bei einem 8bit AM-DIG steht dieser Aufruf nicht zur Verfügung, beim PCDig muß noch die entsprechende LUT (obere oder untere 16Bit, also 0 oder 1) spezifiziert werden.

GIOC|HIOC_DG|PCD_GET|SET_LUT*
    Es wird die 16bit Lookup-Tabelle des AM-DIG/PCDig gelesen/gesetzt. Als Argument muß eine ‘union’ übergeben werden, welche abhängig von der eingestellten Farbtiefe 256/1024/4096 oder 65536 16bit Werte enthält. Beim PCDig ist wiederum der Zusatz zu beachten, daß über 0 oder 1 die obere/untere 16Bit LUT gewählt werden muß.

GIOC|HIOC_DG|PCD_SET_LUT_LIN
    Die 16bit Lookup-Tabelle des AM-DIG/PCDig wird linearisiert. Die Art der Linearisierung ist abhängig von der eingestellten Farbtiefe. Ist diese nicht 16bit, wird eine Seite der Lookup-Tabelle linearisiert, die anderen werden genullt.

GIOC|HIOC_DG|PCD_SET_NORM_TO8
    Will man angeschlossene 10/12/16bit Kameras auf 8bit Farbtiefe reduzieren, muß dieser Aufruf gewählt werden. Achtung, es wird nicht gerundet, nur ‘abgeschnitten’!

GIOC|HIOC_DG|PCD_SET_NORM_TO16
    Um 8/10/12bit Kameras auf 16bit Farbtiefe aufzuweiten, ist dieser Aufruf anzuwenden.

GIOC|HIOC_DG|PCD_GET|SET_EXTIME
    Diese Aufrufe behandeln den auf dem AM-DIG/PCDig befindlichen zusätzlichen Zähler, welcher für besondere Aufgaben gedacht ist. Denkbar wären zum Beispiel das Einstellen von verschiedenen Belichtungszeiten sowohl bei Line-Scan, als auch bei Area-Scan Kameras.
    Voraussetzung auf Seiten der Kamera ist dazu, daß sie über einen sogenannten Trigger-Shutter Eingang verfügt, welcher ein Signal nach Bild 1 auswerten kann:
    Bild 1:
                     Bildausgabe
    ---               ---------               ---
       |             |         |             |
        -------------           -------------
         einstellbare          ^
        Belichtungszeit     Neustart

    Solange ein Low-Pegel anliegt, wird belichtet - sobald eine Low-High Flanke erkannt wird, beginnt automatisch die Bildausgabe.
    Diese Signalfolge gibt das AM-DIG/PCDig als RS422(LVDS)Signal an den Pins 41(+)13(-)/83(+)84(-) des 44/100-poligen Steckers aus, wobei die Belichtungszeit über das mitgelieferte Programm extime_itifg online in den Grenzen von ca. 500ns/140ns bis 500ms/18s in unterschiedlichen Schrittweiten eingestellt werden kann.
    Der Start bzw. kontinuierliche Restart des oben gezeigten Zyklus kann dabei auf verschiedene Weise erfolgen:

    1. automatischer Neustart nach Bildausgabe:

            EXSync_Counter_Enable
            ExtSync_Mode = FEN_Trigger
            Trigger_Gen_Disable

    2. manueller Neustart durch Software-Triggerung:

            EXSync_Counter_Enable
            ExtSync_Mode = SW_Trigger
            Trigger_Gen_Enable
            Trigger_Source = Software

        Die Triggerung erfolgt mit dem Programm swtrig_itifg.

    3. manueller Neustart durch externe Triggerung:

            EXSync_Counter_Enable
            ExtSync_Mode = Ext_Trigger
            Trigger_Gen_Enable
            Trigger_Source = External

    Allgemein muß beachtet werden, daß bei den Punkten 2 und 3 der Triggerimpuls innerhalb von 5s (PCD_WAIT_TRG) gegeben werden muß.
    Auch von Wichtigkeit sind die Polaritäten sowohl des EXSync, als auch des LEN Impulses (letzterer nur bei Punkt 1). Getestet ist dabei folgende Einstellung:

        FEN_NoInvert
        EXSYNC_Pulse_Active_Low.

    Wird eine feste Einstellung der Belichtungszeit gewünscht, kann diese auch in der Konfigurationsdatei durch Anpassung von EXSCLK_14.32_Div???? und EXSCLK_CounterPreset erfolgen. Eine Berechnung ist dabei mit folgender Formel möglich:
                           (Divisor * CounterPreset)
    Belichtungszeit [us] = -------------------------.
                                  14,32 MHz.

[G|H]IOC_[DG|PCD]_[G|S]ET_CAMMD
    Das AM-DIG/PCDig verfügt über einen 3bit/4bit breiten Bus zur Steuerung der Kamera (TTL-Ausgänge), welche auf diese Weise gesetzt und bedingt (es wird nur der interne Zustand zurückgeliefert, da es keine Eingabekanäle sind) gelesen werden können.
    Die Funktion dieses Aufrufs kann sofort mit dem [-m] Parameter des Programms extime_itifg getestet werden.

  AM-DIG spezifisch

GIOC_DG_GET|SET_OLUTPG
    Bei der auf dem 24bit AM-DIG verfügbaren zusätzlichen 8bit Lookup-Tabelle kann ebenfalls eine aktive LUT-Seite (aus 8 verfügbaren) eingestellt/ gelesen werden. Bei 8/16bit Modulen ist dieser Aufruf nicht möglich.

GIOC_DG_GET|SET_OLUT
    Es werden 256 Werte der jeweils aktiven Seite der optionalen Lookup-Tabelle auf dem 24bit AM-DIG gelesen/gesetzt.

  PCDig spezifisch

HIOC_PCD_SET_EXFREE (!)
    /* FILLME */

HIOC_PCD_GET_STMODE (!)
    /* FILLME */

HIOC_PCD_SET_STMODE (!)
    /* FILLME */

HIOC_PCD_GET_ETMODE (!)
    /* FILLME */

HIOC_PCD_SET_ETMODE (!)
    /* FILLME */

HIOC_PCD_GET_FCNT (!)
    /* FILLME */

HIOC_PCD_SET_FCNT (!)
    /* FILLME */

  Software allgemein

GIOC_GE_GET_WIDTH (!)
    Die eingestellte Bildbreite wird ermittelt.

GIOC_GE_GET_HEIGHT (!)
    Die eingestellte Bildhöhe wird ermittelt.

GIOC_GE_GET_DEPTH (!)
    Die Bittiefe des Bildes wird ermittelt.

GIOC_GE_GET_RAWSIZE (!)
    Der Speicherbedarf (in Bytes) des zu erwartenden Bildes wird ausgelesen. Dieser ist abhängig von Breite/Höhe und Farbtiefe.

GIOC_GE_GET_PAGEDSIZE (!)
    Die gerundete Größe der Puffer wird ausgelesen. Sie ergibt sich direkt aus der RAWSIZE plus einer Struktur, welche Informationen zum Bild enthält, gerundet mit der PAGESIZE des Systems.

GIOC_GE_GET|SET_CAMERA
    Sollte ein Acquisitionsmodule mehrere Kameraeingänge besitzen (z.B. AM-VS/PCVision) kann so die aktive Kamera abgefragt/gesetzt werden.

GIOC_GE_SET_DEFCNF (!)
    Für jede Hardware ist eine Standard-Kameraeinstellung in den Treiber eingebaut. Diese wird einmal beim Laden des Modul's aktiviert und kann danach auch über diesen Aufruf gesetzt werden.

GIOC_GE_GET|SET_CAMCNF
    Dieser Aufruf ist der wichtigste und sollte sofort nach dem open(2) des Gerätes erfolgen, da er viele andere Werte (Höhe/Breite/Tiefe und damit Pufferanzahl, etc.) neu setzt/berechnet. Den zu übergebenden ‘union’ kann und sollte man bequem aus einer Kamerakonfigurationsdatei mit der Funktion read_config() der mitgelieferten libiticonfig.a füllen! Natürlich kann die aktive Konfiguration auch ausgelesen werden.

GIOC_GE_GET_SYNCWAIT (!)
    Manchmal kann es wichtig sein, zu ermitteln, ob und wenn ja welche Kamera an einem Eingang der BV-Karte angeschlossen ist. Mit diesem Aufruf wird die Zeit zwischen zwei VSync Signalen ermittelt und zurückgegeben.
    Wird als drittes Argument zu ioctl(2) ein NULL-Zeiger übergeben, ist man an diesem Wert nicht interessiert und möchte nur ein Bild warten (z.B. zur Stabilisierung des Signals nach Kameraumschaltungen).

GIOC_GE_SET_TIMEOUT (!)
    Um bei einem Fehlen des Kamerasignales nicht unbegrenzt auf ein Bild zu warten, kann dem Gerätetreiber eine Zeitbegrenzung mitgeteilt werden. Diese ist in den Grenzen von 0.01 bis 100 (ITI_FPS_MIN - ITI_FPS_MAX) Bilder/Sekunde (invers zur Zeitbegrenzung) zu wählen. Standardwert nach dem laden ist 25 Bilder/Sekunde (ITI_INIT_FPS). Wird mit dem Programm test_itifg gearbeitet und nicht [-r -AR -rate] gesetzt, wird eine Wartezeit von 1s eingestellt.

GIOC_GE_GET_STATS
    Die schon vorhandenen Statistiken, welche vor Version 0.5.1 nur über die an das Bild angehängte struct icp_info_t ausgelesen werden konnten, wurden um einige Elemente, die Ein- /Ausgabe- Kanäle betreffend, erweitert. Ab der genannten Version ist das Auslesen nun auch über diesen Ioctl möglich.

GIOC_GE_SET_STATS
    Ausschließlich die Statistiken der Ein- /Ausgabe- Kanäle werden auf ihre Anfangswerte zurückgesetzt.

SIEHE AUCH
itifg(4), test_itifg(4), ioctl(2)