Kithara »USB Toolkit«

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.

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.

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.

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.