Kithara »Driver Collection«

Das Base Module stellt vielfältige Werkzeuge bereit, z.B. Shared Memory für den Datenaustausch zwischen Anwendung und Kernel:

err = KS_createSharedMem(
        &pAppPtr,                // Application-Adresse
        &pSysPtr,                // Systemadresse des Speichers
        "MySharedMem",           // Global gültiger Name
        40 * MegaBytes,          // Länge in Bytes
        0);                      // Flags, hier 0

Zur Vereinfachung für regelmäßigen Datenaustausch ist eine Daten-Pipe ideal, die intern ebenfalls auf Shared Memory basiert:

err = KS_createPipe(
        &hPipe,                  // Adresse des Pipe-Handles
        "MyValuePipe",           // Name der Pipe
        2,                       // Datengröße (z.B. Messwerte)
        1000000,                 // max. Anzahl Datenelemente
        NULL,                    // reserviert
        0);                      // Flags, hier 0

Nun kann z.B. der Kernel ermittelte Messwerte in der Pipe ablegen:

err = KS_putPipe(
        hPipe,                   // Pipe-Handle
        valueBuffer,             // Zeiger auf Datenpuffer
        valueCount,              // Anzahl der Messwerte
        NULL,                    // hier nicht benutzt
        0);                      // Flags, hier 0

Die Anwendung kann nun die Messwerte aus der Pipe lesen:

err = KS_getPipe(
        hPipe,                   // Pipe-Handle
        buffer,                  // Zeiger auf Datenpuffer
        bufferSize,              // max. Größe des Puffers
        &filledSize,             // wieviel Werte gelesen?
        0);                      // Flags, hier 0

Daten mit variabler Länge (z.B. Messages) lassen sich optimal mit einer Message-Pipe verarbeiten. Diese ist sehr ähnlich zu verwenden.

Angenommen, Ihre Callback-Funktion für den Echtzeit-Timer sieht so aus:

int __stdcall myTimerCallback(
        void* pArgs,             // Adresse der Referenzdaten
        void* pContext);         // Adresse der Kontextdaten

Es gibt nun zwei Wege, um den Anwendercode auf die Kernel-Ebene zu bekommen:

err = KS_createCallBack(
        &hCallBack,              // Adresse des Handles
        myTimerCallback,         // Adresse der Funktion
        pSysAddrOfMyData,        // Referenzparameter
        KSF_KERNEL_EXEC,         // auf der Kernel-Ebene!
        0);                      // Anwendungspriorität, hier 0

Auf diese Weise wird die Funktion in den Kernel-Speicher geladen.

Alternativ lässt sich eine ganze DLL in den Kernel laden:

err = KS_loadKernel(
        &hKernel,                // Adresse des Handles
        "mykernel.dll",          // Dateiname der Kernel-DLL
        "myInitFunction",        // Name der Init-Routine
        pArgs,                   // Referenzparameter
        KSF_KERNEL_EXEC);        // Flags, in Kernel laden

Einmal in den Kernel geladen, kann nun ganz ähnlich ein Kernel-Callback erzeugt werden:

err = KS_createKernelCallBack(
        &hCallBack,              // Adresse des Handles
        hKernel,                 // Kernel-Handle
        "myTimerCallback",       // Name der Funktion
        pSysAddrOfMyData,        // Referenzparameter
        KSF_KERNEL_EXEC,         // auf der Kernel-Ebene!
        0);                      // Anwendungspriorität, hier 0

Die Callback-Handles lassen sich nun als Timer oder Interrupt-Handler anmelden oder z.B. zur Echtzeit-Signalisierung bei eintreffenden Ethernet-Frames.

Hinweis: Vollständige Projekte, die eine Rahmenanwendung in einer der Sprachen C++, C# oder Delphi sowie eine in den Kernel geladene DLL in C++ oder Delphi enthalten, sind Bestandteil jeder Software-Lieferung.

Wenn der direkte I/O-Port-Zugriff genutzt werden soll, ist zunächst der I/O-Bereich für den Direktzugriff freizuschalten:

err = KS_enableIoRange(
        myBaseAddress,           // Basisadresse der Hardware
        8,                       // Anzahl der I/O-Register
        KSF_SIZE_8_BIT);         // Flags, hier byte-weise

Nun können die freigegebenen Hardware-Register direkt adressiert werden:

byte value = KS_inpb(
        myBaseAddress + 2);      // Adresse, 1 Byte lesen
...                              // Byte auswerten
KS_outpb(
        myBaseAddress + 4,       // Adresse, 1 Byte schreiben
        value);                  // Byte schreiben

Wenn die I/O-Basisadresse einer PCI-Karte vom Plug&Play-Manager dynamisch vergeben wurde, kann diese ganz leicht ermittelt werden, indem entweder alle PCI-Baugruppen durchsucht werden, bis die gewünschte (anhand Vendor- und Device-ID) gefunden wird:

err = KS_getBusData(
        &pciData,                // Adresse der PCI-Struktur
        busNumber,               // Bus-Nummer
        slotNumber,              // Gerätenummer und Funktion
        0);                      // Flags, hier 0
if (pciData.vendorID == XXXX && pciData.deviceID == YYYY)
  ...

Oder es wird sofort die gewünschte ID-Kombination gesucht:

err = KS_getRessourceInfo(
        "PCI\\VENxxxx&DEVyyyy",  // ID-Kombination
        &resourceInfo);          // Adresse der Resourcen-Info

Die erhaltenen Datenstrukturen enthalten nun die benötigten Angaben über Interrupt-Leitung und benutzte I/O- oder Speicher-Basisadressen.

Das Einblenden externer Speicherbereiche (Dual-Port-RAM) einer PCI-Karte in den Adressraum der Anwendung und des Kernels erfolgt so:

err = KS_mapPhysMem(
        &pAppPtr,                // Application-Adresse
        &pSysPtr,                // Systemadresse des Speichers
        externalPhysAddr,        // physikalische Adresse
        externalSize,            // Länge des Speicherbereichs
        KSF_PCI_BUS);            // Flags, hier PCI-Bus

Das Allokieren interner Speicherbereiche des PC-RAM für Zugriffe durch die externe Hardware (sogenanntes "Bus-Master-DMA") einer PCI-Karte erfolgt so:

err = KS_allocPhysMem(
        &pAppPtr,                // Application-Adresse
        &pSysPtr,                // Systemadresse des Speichers
        &externalPhysAddr,       // physikalische Adresse
        externalSize,            // Länge des Speicherbereichs
        KSF_PCI_BUS);            // Flags, hier PCI-Bus

Die physikalische Adresse kann nun auf geeignete Weise an die Hardware übermittelt werden, damit diese über den PCI-Bus auf den Speicher zugreifen kann.

Beide Methoden führen dazu, dass sowohl die Anwendung, der Kernel und die externe Hardware direkt (ohne Emulation oder Kopieroperationen) auf den selben Speicher zugreifen können.

Das Clock Module stellt zwei verschiedene Mechanismen bereit – Zeitmessung und Kurzzeitverzögerung.

Die meist benutzte Funktion zur Zeitmessung liefert 100-ns-Einheiten seit dem Start des Systems:

UInt64 time;
err = KS_getClock(
        &time,                   // Adresse der Variablen
        KS_CLOCK_MACHINE_TIME);  // 100-ns seit Systemstart

Diese können auch zur einfacheren Weiterverarbeitung in 64-Bit-Werte umgewandelt werden:

__int64 time64 = time.hi;
time64 <<= 32;
time64 += time.lo;
printf("%Ld Mikrosekunden seit dem Systemstart.\n", time64 / 10);

Statt der (Systemstart-) relativen Zeit ist auch der absolute Zeitpunkt seit dem 1.1.1601 ermittelbar:

err = KS_getClock(
        &time,                   // Adresse der Variablen
        KS_CLOCK_ABSOLUTE_TIME); // 100-ns seit 1.1.1601

Der erhaltene Wert lässt sich leicht mit Windows-Funktionen weiterverarbeiten.

Die Kurzzeitverzögerung realisiert hochgenaue Verzögerungen, programmierbar in 100-ns-Schritten und mit einer Abweichung von nur wenigen Nanosekunden (auf der Kernel-Ebene):

err = KS_microDelay(
        38);                     // hier 3,8 Mikrosekunden

Dies ist oftmals sehr nützlich beim Zugriff auf Hardware, wenn zeitliche Bedingungen einzuhalten sind.

Auf einfache Weise können Sie sicherstellen, dass bei einem eventuellen Fehler Ihres Anwendungsprogrammes das System in einen sicheren Zustand überführt werden kann. Erstellen Sie eine Callback-Funktion für die Kernel-Ebene, um dies zu erreichen:

int __stdcall myEmergencyCallback(
        void* pArgs,             // Adresse der Referenzdaten
        void* pContext);         // Adresse der Kontextdaten

Hierfür wird nun ein Callback-Objekt erzeugt:

err = KS_createCallBack(
        &hCallBack,              // Adresse des Handles
        myEmergencyCallback,     // Adresse der Funktion
        pSysAddrOfMyData,        // Referenzparameter
        KSF_DIRECT_EXEC,         // auf der Kernel-Ebene!
        0);                      // Anwendungspriorität, hier 0

Diese Callback-Funktion wird nun als System-Handler angemeldet:

err = KS_installSystemHandler(
        KS_SYSTEM_PROCESS_ABORT, // bei Programmabbruch
        hCallBack,               // Callback-Handle
        0);                      // Flags, hier 0

Falls nun ein unerwarteter Programmabbruch erfolgt, ohne vorher die benutzten Ressourcen ordnungsgemäß abzumelden, wird auf der Kernel-Ebene die Emergency-Callback-Funktion gerufen.

"Unerwartete Programmabbrüche" sind z.B. ein Programmabsturz oder auch das Abbrechen durch den Task Manager oder den Debugger der Entwicklungsumgebung.

Für die Realisierung eines "virtuellen COM-Ports" erstellen Sie verschiedene Callback-Routinen für die Ereignisse CREATE, CLOSE, READ, WRITE und CONTROL. Zum Beispiel für CONTROL:

int __stdcall myControlCallback(
        void* pArgs,             // Adresse der Referenzdaten
        void* pContext)          // Adresse der Kontextdaten
{ ...
  if (pContext->controlCode == SERIAL_SET_BAUD_RATE)
    ...

Für alle Routinen werden nun Callback-Objekte erzeugt:

err = KS_createCallBack(
        &functions.hOnControl,   // Adresse des Handles
        myControlCallback,       // Adresse der Funktion
        pSysAddrOfMyData,        // Referenzparameter
        KSF_DIRECT_EXEC,         // auf der Kernel-Ebene!
        0);                      // Anwendungspriorität, hier 0

Anschließend kann das "virtuelle COM-Port" erzeugt werden:

err = KS_createDevice(
        &pAppPtr->hDevice_,      // Addresse des Handles
        "COM77",                 // Device-Name
        &functions,              // Struktur mit Callback-Handles
        KSF_SERIAL_PORT);        // Flags, "virtueller COM-Port"

Damit steht anderen Anwendungen eine weitere serielle Schnittstelle unter dem Namen "COM77" zur Verfügung, die sich von "echten" Schnittstellen nicht unterscheidet. Sie können damit oftmals vorhandene Anwendungen weiter betreiben, ohne diese neu programmieren zu müssen.

An einer PS/2-Tastatur ist es einfach möglich, spezielle Tastencodes für eine besondere Kernel-Funktion zu vereinbaren. Angenommen, es soll eine spezielle Behandlung für Ctrl-Shift-Alt-F1 erfolgen:

int __stdcall myKeyboardCallBack(
        void* pArgs,             // Adresse der Referenzdaten
        void* pContext)          // Adresse der Kontextdaten
{ ...
  if ((pUserContext->modifier & KSF_KEY_SHIFT) != 0 &&
      (pUserContext->modifier & KSF_KEY_CTRL) != 0 &&
      (pUserContext->modifier & KSF_KEY_ALT) != 0 &&
      (pUserContext->key == 0x3B))
    specialF1Handler();          // Spezielle F1-Routine
  ...

Diese Funktion kann nun als Handler angemeldet werden:

err = KS_createKeyHandler(
        KSF_KEY_FUNCTION,        // nur Funktionstasten abfangen
        hSpecialF1CallBack,      // Handler, hier Callback
        0);                      // Flags, hier 0

In industriellen Anlagen ist es oftmals erwünscht, spezielle Sondertasten für den Bediener zu sperren. Dazu gehören z.B. die Windows-Tasten, Ctrl-Alt-Del, Ctrl-Esc, Alt-Esc und Alt-Tab. Um diese alle zu sperren, genügt folgender Funktionsaufruf:

err = KS_createKeyHandler(
        KSF_KEY_SYSTEM,          // Alle Systemtasten
        NULL,                    // Kein Handler benötigt
        KSF_IGNORE_KEY);         // Tasten sind zu ignorieren

Es ist ein Datenstrom an einer seriellen Schnittstelle zu beobachten und zu protokollieren. Dazu müssen alle WRITE-Request- und alle READ-Complete-Aufrufe erfasst werden. Die Daten werden über Message-Pipes geleitet:

int __stdcall mySerialFilterCallBack(
        void* pArgs,             // Adresse der Referenzdaten
        void* pContext)          // Adresse der Kontextdaten
{ ...
  if ((pUserContext->ctxType == KS_FILTER_WRITE_REQUEST)
    err = KS_putPipe(
        pData->hWrPipe,          // Pipe-Handle
        pContext->pBytes,        // Daten
        pContext->length,        // Länge
        NULL, 0);

  if ((pUserContext->ctxType == KS_FILTER_READ_COMPLETE)
    err = KS_putPipe(
        pData->hRdrPipe,          // Pipe-Handle
        pContext->pBytes,        // Daten
        pContext->length,        // Länge
        NULL, 0);
  ...

Ein Filter wird erzeugt, wobei die Schnittstelle noch nicht geöffnet sein darf:

err = KS_createFilter(
        &hFilter,                // Adresse d. Filter-Handles
        "COM1",                  // Name des Ports
        0);                      // Flags, hier 0

Die Funktion kann nun als Handler angemeldet werden:

err = KS_installFilterHandler(
        hFilter,                 // Filter-Handle
        KS_FILTER_WRITE_REQUEST, // Ereignis
        hSerialFilterCallBack,   // Handler, hier Callback
        0);                      // Flags, hier 0

err = KS_installFilterHandler(
        hFilter,                 // Filter-Handle
        KS_FILTER_READ_COMPLETE, // Ereignis
        hSerialFilterCallBack,   // Handler, hier Callback
        0);                      // Flags, hier 0

Angenommen, es soll folgende Callback-Funktion als Interrupt-Handler fungieren:

int __stdcall myInterruptHandler(
        void* pArgs,             // Adresse der Referenzdaten
        void* pContext);         // Adresse der Kontextdaten

Hiermit erstellen Sie ein Callback-Objekt (siehe Kernel Module) mit dem Flag KSF_DIRECT_EXEC.

Zur Anmeldung des Interrupt-Handlers sind zunächst die Ressourcen-Informationen zu ermitteln:

KSResourceInfoEx info;
err = KS_getResourceInfoEx(
        "PCI\\VEN_10ec&DEV_8139",// Hardware-ID der PCI-Karte
        &info);                  // Zu füllende Info-Struktur

Damit lässt sich nun der Interrupt-Handler anmelden:

err = KS_createDeviceInterrupt(
        &hInterrupt,             // Adresse des Handles
        &info,                   // Info-Struktur
        hCallBack,               // Callback-Handle
        KSF_ACCEPT_PENDING |
          KSF_PCI_INTERRUPT);    // Flags, hier PCI

Es lassen sich auch mehrere Handler beim selben IRQ anmelden, z.B. eine Callback-Funktion für die Kernel-Ebene und eine weitere innerhalb des Anwendungskontexts.

Verwenden Sie folgende Funktion, um alle COM-Ports aufzulisten:

err = KS_enumDevices(
        "COM",                   // nach COM-Ports suchen
        i,                       // Zähler, mit 0 beginnend
        portNameBuf,             // Puffer für COM-Port-Namen
        0);                      // Flags, hier 0

Die Schnittstelle lässt sich dann wie folgt öffnen:

KSResourceInfoEx info;
err = KS_openSerialPort(
        &hPort,                  // Adresse des Handles
        portNameBuf,             // Name des Ports (z.B. "COM1")
        "9600,n,8,1",            // Initialisierung
        KSF_KERNEL_EXEC);        // Kernel-Implementierung

So senden wir Daten, z.B. eine Messwertanforderung an eine Gerät:

err = KS_xmitPort(
        hPort,                   // Port-Handle
        NULL,                    // Signalisierung (Post Mode)
        message,                 // Pufferadresse
        0,                       // Länge, zu senden (auto)
        NULL,                    // Länge, gesendet
        KSF_DONT_WAIT);          // Flags: ohne Blockierung

Jederzeit lässt sich ermitteln, wie viele Zeichen bereits empfangen wurden:

err = KS_getPortState(
        hPort,                   // Port-Handle
        &state,                  // Adresse der Status-Struktur
        0);                      // Flags: here 0
printf("Es wurden %d Zeichen empfangen.\n", state.recvAvail);

Der Empfang kann folgendermaßen aussehen (im Wait-Mode auf der Anwendungsebene):

err = KS_recvPort(
        hPort,                   // Port-Handle
        NULL,                    // Signalisierung (Wait Mode)
        pBuffer,                 // Adresse des Datenpuffers
        state.recvAvail,         // Länge, zu empfangen
        &received,               // Länge, empfangen
        KSF_USE_TIMEOUTS);       // Flags: Timeout-Überwachung

Verwenden Sie folgende Funktion, um alle USB-Geräte aufzulisten:

err = KS_enumDevices(
        "USB",                   // nach USB-Geräten suchen
        i,                       // Zähler, mit 0 beginnend
        deviceNameBuf,           // Puffer für Gerätenamen
        0);                      // Flags, hier 0

Mit dem erhaltenen Namen lässt sich der Config-Deskriptor ermitteln, um z.B. nach einem bestimmten HID-Gerätetyp zu suchen:

err = KS_execUsbCommand(
        deviceNameBuf,           // Gerätename
        KS_USB_GET_CONFIG_DESCRIPTOR,
        0,                       // Index des Deskriptors
        pBuf,                    // Puffer
        64000,                   // Puffergröße
        KSF_ALTERNATIVE);        // Flags

Ein bereits vorhandener Treiber kann ersetzt werden:

strcpy(infPath+GetSystemDirectory(infPath,256),"\\Kdemo.inf");
err = KS_updateDriver(
        deviceNameBuf,           // Gerätename
        infPath,                 // INF-Datei
        0);                      // Flags, hier 0

Das gefundene Gerät kann nun geöffnet werden. Wenn es bekannt ist, können Sie hier aber auch den Gerätenamen direkt angeben:

err = KS_openUsbDevice(
        &hDevice,                // Adresse des Handles
        "USB\\VID_10CF&PID_5500",// Gerätename
        0);                      // Flags, hier 0

Die eigentliche Kommunikation erfolgt über sogenannte Endpoints. Es gibt bis 15 Sende- und 15 Empfangs-Endpunkte zu einem Gerät:

err = KS_getUsbPort(
        hDevice,                 // Device-Handle
        &hPort,                  // Adresse des Handles
        endpointAddress,         // Nummer des Endpoints
        KSF_INTERRUPT_TRANSFER); // Flags: Transferart

Die Kommunikation selbst erfolgt nun ähnlich der seriellen Kommunikation im Serial Module.

Wenn Sie eine Callback-Funktion erzeugt haben (siehe Kernel Module), können Sie diese als Timer-Callback wie folgt anmelden:

const int ms = 10000;            // Millisekunden
err = KS_createTimer(
        &hTimer,                 // Adresse des Handles
        period * ms,             // Timerperiode in 100 ns
        hTimerCallBack,          // Callback-Handle
        KSF_DONT_START);         // Flags: noch nicht starten

Der Timer lässt sich nun für zyklische Ausführung starten:

err = KS_startTimer(
        hTimer,                  // Timer-Handle
        0,                       // Flags, hier 0
        period * ms);            // Timerperiode in 100 ns

…und jederzeit wieder stoppen:

err = KS_stopTimer(
        hTimer);                 // Timer-Handle

…oder auch erneut starten, z.B. für einmaligen Aufruf:

err = KS_startTimer(
        hTimer,                  // Timer-Handle
        KSF_ONE_SHOT,            // Flags, einmalig
        period * ms);            // Timerdauer in 100 ns

Ein laufender Timer kann jederzeit abgebrochen werden, was sich sehr gut für Watchdog-Anwendungen eignet:

err = KS_cancelTimer(
        hTimer);                 // Timer-Handle

In dem Fall beginnt bei zyklischen Timern die Wartezeit erneut.