Kithara »RealTime Suite«

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.

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 (die Wartezeit beginnt erneut):

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

Zum Betrieb des Timers auf der Kernel-Ebene in Echtzeit ist zunächst der Hardware-Timer zu initialisieren:

const int us = 10;               // Mikrosekunden
err = KS_setTimerResolution(
        resolution * us,         // Timerperiode in 100 ns
        KSF_HIGH_PRECISION);     // Flags, hier High-Prec.

NEU! Auf APIC-Systemen ist jetzt auch der High-Precision-Modus verwendbar.

Nun kann der Echtzeit-Timer angemeldet werden:

err = KS_createTimer(
        &hTimer,                 // Adresse des Handles
        period * us,             // Timerperiode in 100 ns
        hTimerCallBack,          // Callback-Handle
        KSF_REALTIME_EXEC);      // Flags: Echtzeit-Timer

Damit wird beinahe jegliches Jitter vermieden!

Zunächst ist die Echtzeit-Umgebung zu aktivieren (siehe RealTime Module). Danach können Tasks erzeugt werden:

err = KS_createTask(
        &hTask,                  // Adresse des Handles
        hCallBack,               // Callback-Handle
        250,                     // Prioritätsstufe (64-255)
        KSF_DONT_START);         // Flags, noch nicht starten

Das Flag KSF_DONT_START legt fest, dass die Task noch nicht zu starten ist – sie ist suspendiert. Ein Starten erfolgt über:

err = KS_resumeTask(
        hTask);                  // Task-Handle

Um die Task nochmals an der Ausführung zu hindern, kann sie wiederum suspendiert werden:

err = KS_suspendTask(
        hTask);                  // Task-Handle

Wenn eine Task sich selbst unterbrechen soll (um später von einer anderen wieder aufgeweckt zu werden), kann sie ebenfalls diese Funktion rufen:

err = KS_suspendTask(
        NULL);                   // Diese Task

Die Task lässt sich auch direkt als Timer-Task starten:

err = KS_createTimer(
        &hTimer,                 // Adresse des Handles
        50 * us,                 // Timer-Periode in 100 ns
        hTask,                   // Handle der Timer-Task
        KSF_REALTIME_EXEC);      // Flags, Echtzeit-Ausführung

Nun wird die Task zyklisch mit einer Periode von 50 µs (20 kHz) bei jedem Timer-Takt aktiviert.

Wenn eine Task beendet werden soll, kann sie jederzeit die folgende Funktion rufen:

err = KS_exitTask(
        exitCode);               // Beendigungswert der Task

Zuerst wird der Netzwerkadapter geöffnet, wobei dessen Hardware-ID anzugeben ist:

err = KS_openAdapter(
        &hAdapter,               // Adresse des Handles
        "VEN8086&DEV1226",       // Hardware-ID des Adapters
        100,                     // RecvPool-Länge
        100,                     // SendPool-Länge
        0);                      // Flags, hier 0

Zum Senden ist zunächst ein Paket aus dem Pool anzufordern und zu befüllen:

err = KS_requestPacket(
        hAdapter,                // Adapter-Handle
        &pPacket,                // Zeiger auf Ethernet-Paket
        KSF_IP_PACKET);          // Flags, hier IP-Paket
...                              // Paket füllen
err = KS_sendPacket(
        hAdapter,                // Adapter-Handle
        pPacket,                 // Adresse des Ethernet-Pakets
        KSF_IP_PACKET);          // Flags, hier IP-Paket

Beim Empfang ist der Ablauf umgekehrt: Zuerst wird ein Paket abgerufen und nach der Auswertung der Daten wieder freigegeben:

err = KS_recvPacket(
        hAdapter,                // Adapter-Handle
        &pPacket,                // Zeiger auf Ethernet-Paket
        KSF_IP_PACKET);          // Flags, hier IP-Paket
...                              // Paket auslesen
err = KS_releasePacket(
        hAdapter,                // Adapter-Handle
        pPacket,                 // Adresse des Ethernet-Pakets
        KSF_IP_PACKET);          // Flags, hier IP-Paket

Sie können auch eine Callback-Funktion zum Echtzeitempfang registrieren:

err = KS_installPacketHandler(
        hAdapter,                // Adapter-Handle
        KS_PACKET_RECV,          // bei Paketempfang aufrufen
        hRecvCallback,           // Handle des Callback-Objekts
        0);                      // Flags, hier 0

Die Möglichkeiten des Packet Fast Modules gelten auch hier. Zusätzlich werden auch Gigabit-Ethernet-Controller unterstützt (siehe Hardware-Kompatibilitätsliste).

Zuerst wird der Netzwerkadapter geöffnet, wobei dessen Hardware-ID anzugeben ist:

err = KS_openAdapter(
        &hAdapter,               // Adresse des Handles
        "VEN8086&DEV1226",       // Hardware-ID des Adapters
        100,                     // RecvPool-Länge
        100,                     // SendPool-Länge
        0);                      // Flags, hier 0

Zum Senden ist zunächst ein Paket aus dem Pool anzufordern und zu befüllen:

err = KS_requestPacket(
        hAdapter,                // Adapter-Handle
        &pPacket,                // Zeiger auf Ethernet-Paket
        KSF_IP_PACKET);          // Flags, hier IP-Paket
...                              // Paket füllen
err = KS_sendPacket(
        hAdapter,                // Adapter-Handle
        pPacket,                 // Adresse des Ethernet-Pakets
        KSF_IP_PACKET);          // Flags, hier IP-Paket

Beim Empfang ist der Ablauf umgekehrt: Zuerst wird ein Paket abgerufen und nach der Auswertung der Daten wieder freigegeben:

err = KS_recvPacket(
        hAdapter,                // Adapter-Handle
        &pPacket,                // Zeiger auf Ethernet-Paket
        KSF_IP_PACKET);          // Flags, hier IP-Paket
...                              // Paket auslesen
err = KS_releasePacket(
        hAdapter,                // Adapter-Handle
        pPacket,                 // Adresse des Ethernet-Pakets
        KSF_IP_PACKET);          // Flags, hier IP-Paket

Sie können auch eine Callback-Funktion zum Echtzeitempfang registrieren:

err = KS_installPacketHandler(
        hAdapter,                // Adapter-Handle
        KS_PACKET_RECV,          // bei Paketempfang aufrufen
        hRecvCallback,           // Handle des Callback-Objekts
        0);                      // Flags, hier 0

Zuerst muss die Netzwerkverbindung geöffnet werden (siehe Packet Module). Damit wird der EtherCAT-Master geöffnet:

err = KS_openEcatMaster(
        &hMaster,                // Adresse des Handles
        hAdapter,                // Netzwerk-Adapter-Handle 
        &pMasterDescApp,         // Master-Deskriptor (Anwendung)
        &pMasterDescSys, 0);     // Master-Deskriptor (Kernel)

Die Deskriptor-Struktur beschreibt die EtherCAT-Topologie vollständig:

name = pMasterDescApp->slaves[5]->objs[0]->vars[1].name;

Für den Prozessdatenaustausch ist zunächst ein Dataset zu erzeugen:

err = KS_createDataSet(
        &hDataset, 0);           // Adresse des Handles

Diesem Dataset werden nun die gewünschten Slaves (z.B. I/O-Klemmen) oder Prozessdatenobjekte hinzugefügt:

err = KS_assignDataSet(
        hDataset,                // Dataset-Handle
        NULL, NULL, NULL,        // Objektadressen
        pMasterDescApp->slaves[slaveIndex], 0); // Deskriptor

Es ist hier auch möglich, bereits die Speicheradressen der Variablen zurückliefern zu lassen. Auch Servicedatenobjekte (SDO) lassen sich schreiben und lesen, z.B. der Wandlungsbereich einer Analog-Eingangsklemme auswählen:

err = KS_postDataObj(
        pMasterDescApp->slaves[sdo4],       // SDO-Deskriptor
        pDataBuffer, 0);         // zu schreibende Daten

Nun wollen wir den State wechseln, um den Prozessdatenaustausch zu starten:

err = KS_changeState(
        pMasterDescApp,          // Master-Deskriptor
        KS_STATE_OP, 0);         // State (OPERATIONAL)

Beim zyklischen Prozessdatenaustausch nehmen Sie vermutlich in einer Echtzeit-Timer-Funktion eine Berechnung vor und senden neue Solldaten an die Slaves:

err = KS_postDataSet(
        pData->hDataset, 0);     // Dataset-Handle

Der Datentransport zu den Slaves erfolgt im Hintergrund. Beim nächsten Timertakt übernehmen Sie die empfangenen Daten wieder in das Dataset:

err = KS_readDataSet(
        pData->hDataset, 0);     // Dataset-Handle

Der Zugriff auf die einzelnen Variablen erfolgt mit KS_readDataObj oder direkt über die in den Deskriptoren gespeicherten Adressen im Shared Memory.

Als erstes wird immer ein Port einer CAN-Hardware geöffnet:

err = KS_openCan(
          &hCan,                  // Adresse des CAN-Port-Handle
          pDeviceName,            // Gerätename der CAN-Karte
          port,                   // Port-Nummer auf der Karte
          KS_CAN_BAUD_500K, 0);   // Baudrate

Nach diesem Schritt ist es möglich, Nachrichten zu senden und zu empfangen:

KSCanMsg msg;
          msg.identifier = 0x124;
          msg.msgType    = KS_CAN_MSGTYPE_STANDARD;
          msg.dataLength = 2;
          msg.msgData[0] = 0x4B;  // Sende ein 'K'
          msg.msgData[1] = 0x49;  // Sende ein 'I'

Die CAN-Nachricht wird gesendet:

err = KS_xmitCanMsg(
          hCan,                   // Handle des CAN-Ports
          &msg, 0);               // Adresse des KSCanMsg-Objekts

Wir prüfen, ob eine CAN-Nachricht am Empfang vorliegt:

err = KS_recvCanMsg(
          hCan,                   // Handle des CAN-Ports
          &canMsg, 0);            // Adresse des KSCanMsg-Objekts

Um eine Echtzeit-Reaktion zu erreichen, können wir eine Callback-Funktion anmelden, die auf der Kernel-Ebene im Kontext der Interrupt Service Routine sofort gerufen wird, wenn eine CAN-Nachricht eintrifft. Wie Sie bei gegebener Callback-Funktion ein Callback-Handle erzeugen, sehen Sie im Kernel Module.

err = KS_installCanHandler(
          hCan,                   // Handle des CAN-Ports
          KS_CAN_RECV,            // Ereignis-Code (hier bei Empfang)
          hRecvCallBack, 0);      // Handle des Callback-Objektes

Die Callback-Funktion selbst wird nun in Echtzeit gerufen, sobald eine CAN-Nachricht eintrifft. Auch bei verschiedenen anderen Ereignissen (z.B. Filter, RTR, Fehlerzustand) kann ein Callback gerufen werden.

Für eine passive Busanalyse muss der CAN-Controller in den "Listen Only"-Modus geschaltet werden. Dies geschieht so:

err = KS_execCanCommand(
          hCan,                   // Handle des CAN-Ports
          KS_SET_LISTEN_ONLY, null, 0); // Setze "Listen Only"-Modus