Kithara »Realtime Suite«

The Base Module provides multiple functions, e.g. shared memory for data exchange between application and kernel:

err = KS_createSharedMem(
        &pAppPtr,                // Application address
        &pSysPtr,                // System address of memory
        "MySharedMem",           // Globally valid name
        40 * MegaBytes,          // Length in bytes
        0);                      // Flags, here 0

For the simplification of periodical data exchange is it ideal to use a data pipe, which is also based on shared memory:

err = KS_createPipe(
        &hPipe,                  // Address of pipe handle
        "MyValuePipe",           // Name of pipe
        2,                       // Data size (e.g. measurement values)
        1000000,                 // max. number of data elements
        NULL,                    // reserved
        0);                      // Flags, here 0

Now you can deposit the measured values in the pipe:

err = KS_putPipe(
        hPipe,                   // Pipe handle
        valueBuffer,             // Pointer to data buffer
        valueCount,              // Number of values
        NULL,                    // Not used here
        0);                      // Flags, here 0

Application can read measured values from the pipe:

err = KS_getPipe(
        hPipe,                   // Pipe handle
        buffer,                  // Pointer to data buffer
        bufferSize,              // max. number of values
        &filledSize,             // How many values read?
        0);                      // Flags, here 0

Variable-length data (e.g. messages) can be best handled with a message pipe. The usage is similar to the above mentioned way.

Assuming that your callback-function for the real-time timer looks like that:

int __stdcall myTimerCallback(
        void* pArgs,             // Address of reference data
        void* pContext);         // Address of context data

There are two ways to get the user code to the kernel level:

err = KS_createCallBack(
        &hCallBack,              // Address of handle
        myTimerCallback,         // Address of function
        pSysAddrOfMyData,        // Reference parameter
        KSF_KERNEL_EXEC,         // on the kernel level!
        0);                      // Application priority, here 0

This way a function is loaded into the kernel memory.

Alternativly, you load a whole DDL into the kernel:

err = KS_loadKernel(
        &hKernel,                // Address of handle
        "mykernel.dll",          // File name of kernel DLL
        "myInitFunction",        // Name of init routine
        pArgs,                   // Reference parameter
        KSF_KERNEL_EXEC);        // Flags, load into kernel

If it is once loaded in the kernel, you can create a kernel callback:

err = KS_createKernelCallBack(
        &hCallBack,              // Address of handle
        hKernel,                 // Kernel Handle
        "myTimerCallback",       // Name of function
        pSysAddrOfMyData,        // Reference parameter
        KSF_KERNEL_EXEC,         // on the kernel level!
        0);                      // Application priority, here 0

The callback handles can now be used as timer or interrupt handlers or to a real-time signalization for incoming Ethernet frames.

Hint:Complete Projects, for applications in languages like C++, C# or Delphi and also DDLs, which are loaded into kernel in C++ or Delphi, are components of every software delivery.

If you want to use direct I/O port access, you have to enable the I/O area for the direct access:

err = KS_enableIoRange(
        myBaseAddress,           // Basis addresses of hardware
        8,                       // Number of I/O register
        KSF_SIZE_8_BIT);         // Flags, here byte-wise

Now, you can address the enabled hardware-register:

byte value = KS_inpb(
        myBaseAddress + 2);      // Address, 1 byte read
...                              // Byte analyse
KS_outpb(
        myBaseAddress + 4,       // Address, 1 byte write
        value);                  // Byte write

If the I/O basis address of a PCI card is dynamical allocated from the Plug&Play-Manager, is it easy to trace by either all PCI assemblies will be browsed till the the vendor and device id is founded:

err = KS_getBusData(
        &pciData,                // Address of PCI-structure
        busNumber,               // Bus-number
        slotNumber,              // Device number and function
        0);                      // Flags, here 0
if (pciData.vendorID == XXXX && pciData.deviceID == YYYY)
  ...

Or immediatly browsed by the desired id combination:

err = KS_getRessourceInfo(
        "PCI\\VENxxxx&DEVyyyy",  // ID combination
        &resourceInfo);          // Address of resource info

The received data structures containing all necessary information about interrupt lines and used I/O or memory basis addresses.

The blending of external memory areas (Dual Port RAM) of a PCI card into the address room of the application and kernels takes place like:

err = KS_mapPhysMem(
        &pAppPtr,                // Application address
        &pSysPtr,                // System address of memory
        externalPhysAddr,        // physical address
        externalSize,            // Length of memory area
        KSF_PCI_BUS);            // Flags, here PCI bus

The allocating of internal memory areas of the PC RAM for access by external hardware takes place like:

err = KS_allocPhysMem(
        &pAppPtr,                // Application address
        &pSysPtr,                // System addresss of memory
        &externalPhysAddr,       // physical address
        externalSize,            // Length of memory area
        KSF_PCI_BUS);            // Flags, here PCI-Bus

The physical address can be delivered to the hardware to get access to the memory via PCI bus.

Both methods come to the conclusion, that application, the kernel and the external hardware are able to get directly access (withput emulation or copying operations) to the same memory.

The Clock Module provides two mechanisms – time measuring and short-time delay.

The most used function to time measuring delivers 100 ns units since system start:

UInt64 time;
err = KS_getClock(
        &time,                   // Address of variable
        KS_CLOCK_MACHINE_TIME);  // 100 ns since system start

For processing , converting into 64-bit-values:

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

You also can get the absolute point of time since 1.1.1601 :

err = KS_getClock(
        &time,                   // Address of variable
        KS_CLOCK_ABSOLUTE_TIME); // 100-ns seit 1.1.1601

If you want to process with the received value you can easily use Windows functions.

The short-time delay realizes high precision delays, programmable in 100 ns steps with a difference in a few nanoseconds (on kernel level):

err = KS_microDelay(
        38);                     // here 3,8 microseconds

Thats frequently usefull for access to hardware, if you have to keep in time conditions.

You can simply make sure, that if your application programm has got an error your system will directed in a safety state. Create a callback function for the kernel level to reach this:

int __stdcall myEmergencyCallback(
        void* pArgs,             // Address of reference data
        void* pContext);         // Address of context data

Therefore, a callback object will be created:

err = KS_createCallBack(
        &hCallBack,              // Address of handle
        myEmergencyCallback,     // Address of function
        pSysAddrOfMyData,        // Reference parameter
        KSF_DIRECT_EXEC,         // on kernel level!
        0);                      // Application priority, here 0

This Callback function will be announced as system handle:

err = KS_installSystemHandler(
        KS_SYSTEM_PROCESS_ABORT, // on programm abortion
        hCallBack,               // Callback handle
        0);                      // Flags, here 0

If there is a unexpected programm abortions without logging off all used resources, the emergency callback function appears.

"Unexpected program abortions" are e.g. a program crash or the abortion by Task Manager or the debugger in developing area.

For the realization of a "virtual COM port" you can create different callback rountines for the following events CREATE, CLOSE, READ, WRITE and CONTROL. E.g. for CONTROL:

int __stdcall myControlCallback(
        void* pArgs,             // Address of reference data
        void* pContext)          // Address of context data
{ ...
  if (pContext->controlCode == SERIAL_SET_BAUD_RATE)
    ...

Callback objekts will be created for all routines:

err = KS_createCallBack(
        &functions.hOnControl,   // Address of handle
        myControlCallback,       // Address of function
        pSysAddrOfMyData,        // Reference parameter
        KSF_DIRECT_EXEC,         // on kernel level!
        0);                      // Application priority , here 0

Afterwards, "virtual COM ports" can be created:

err = KS_createDevice(
        &pAppPtr->hDevice_,      // Address of handle
        "COM77",                 // Device name
        &functions,              // Structure with callback handle
        KSF_SERIAL_PORT);        // Flags, "virtual COM port"

Therewith are other applications for another serial interfaces under the name "COM77" available, which can not be differenced to "real" interfaces. You also can operate with existing application and you dont have to programm they new.

It is quite easy possible to declare special key codes for kernel functions on a PS/2 keyboard. Assuming, we want to have a special handling for Ctrl-Shift-Alt-F1:

int __stdcall myKeyboardCallBack(
        void* pArgs,             // Address of reference data
        void* pContext)          // Address of context data
{ ...
  if ((pUserContext->modifier & KSF_KEY_SHIFT) != 0 &&
      (pUserContext->modifier & KSF_KEY_CTRL) != 0 &&
      (pUserContext->modifier & KSF_KEY_ALT) != 0 &&
      (pUserContext->key == 0x3B))
    specialF1Handler();          // Spezial F1-routines
  ...

This function can be announced as handler:

err = KS_createKeyHandler(
        KSF_KEY_FUNCTION,        // Catch only function keys
        hSpecialF1CallBack,      // Handler, here callback
        0);                      // Flags, here 0

In industrial facilities is it frequently desired to lock special keys for the operator. These are e.g. the Windows keys , Ctrl-Alt-Del, Ctrl-Esc, Alt-Esc and Alt-Tab. To lock these you only have to call the following function:

err = KS_createKeyHandler(
        KSF_KEY_SYSTEM,          // All system keys
        NULL,                    // No handler required
        KSF_IGNORE_KEY);         // Ignoring keys

The data flow on serial interfaces can be monitored or logged. To do this you have to collect all WRITE-Request and all READ-Complete calls. The data will be redirected via message-pipes:

int __stdcall mySerialFilterCallBack(
        void* pArgs,             // Address of reference data
        void* pContext)          // Address of context data
{ ...
  if ((pUserContext->ctxType == KS_FILTER_WRITE_REQUEST)
    err = KS_putPipe(
        pData->hWrPipe,          // Pipe handle
        pContext->pBytes,        // Data
        pContext->length,        // Length
        NULL, 0);

  if ((pUserContext->ctxType == KS_FILTER_READ_COMPLETE)
    err = KS_putPipe(
        pData->hRdrPipe,         // Pipe handle
        pContext->pBytes,        // Data
        pContext->length,        // Length
        NULL, 0);
  ...

A filter will be created, if the interface is not opened:

err = KS_createFilter(
        &hFilter,                // Address of filter handle
        "COM1",                  // Name of port
        0);                      // Flags, here 0

The function can be announced as handler:

err = KS_installFilterHandler(
        hFilter,                 // Filter handle
        KS_FILTER_WRITE_REQUEST, // Events
        hSerialFilterCallBack,   // Handler, here callback
        0);                      // Flags, here 0

err = KS_installFilterHandler(
        hFilter,                 // Filter handle
        KS_FILTER_READ_COMPLETE, // Events
        hSerialFilterCallBack,   // Handler, here callback
        0);                      // Flags, hEre 0

Assuming, the following callback function configurated as interrupt handler:

int __stdcall myInterruptHandler(
        void* pArgs,             // Address of reference data
        void* pContext);         // Address of context data

If you want to create callback objects with the flag KSF_DIRECT_EXEC , please note Kernel Module.

If you want to announce an interrupt handler, you have to detect the resource information at first :

KSResourceInfoEx info;
err = KS_getResourceInfoEx(
        "PCI\\VEN_10ec&DEV_8139",// Hardware-ID of PCI card
        &info);                  // To filling info structure

Therewith you can announce the Interrupt handler:

err = KS_createDeviceInterrupt(
        &hInterrupt,             // Address of handle
        &info,                   // Info structure
        hCallBack,               // Callback handle
        KSF_ACCEPT_PENDING |
          KSF_PCI_INTERRUPT);    // Flags, here PCI

You can announce multiple handler for the same IRQ, e.g. a callback function for the kernel level and one further within the application context.

Use the following function to list up all COM ports:

err = KS_enumDevices(
        "COM",                   // Searching COM ports 
        i,                       // Counter, strating with 0 
        portNameBuf,             // Puffer for COM port names
        0);                      // Flags, here 0

The interfaces can be opened like the following:

KSResourceInfoEx info;
err = KS_openSerialPort(
        &hPort,                  // Address of handle
        portNameBuf,             // Name of ports (e.g. "COM1")
        "9600,n,8,1",            // Initialising
        KSF_KERNEL_EXEC);        // Kernel implementation

Thats how we send data, e.g. a measuring request to a device:

err = KS_xmitPort(
        hPort,                   // Port handle
        NULL,                    // Signalisation (Post Mode)
        message,                 // Puffer address
        0,                       // Length, to send (auto)
        NULL,                    // Length, sent
        KSF_DONT_WAIT);          // Flags: without blocking

Anytime, you can detect the number of received characters:

err = KS_getPortState(
        hPort,                   // Port handle
        &state,                  // Address of state structure
        0);                      // Flags: here 0
printf("%d characters received.\n", state.recvAvail);

The receiving looks like the following (in Wait Mode on application level):

err = KS_recvPort(
        hPort,                   // Port handle
        NULL,                    // Signalisation (Wait Mode)
        pBuffer,                 // Address of  data puffer
        state.recvAvail,         // Length, to receive
        &received,               // Length, received
        KSF_USE_TIMEOUTS);       // Flags: time out monitoring

Use the following function to list up all USB devices:

err = KS_enumDevices(
        "USB",                   // Searching USB devices
        i,                       // Counter, starting with 0
        deviceNameBuf,           // Puffer for device name
        0);                      // Flags, here 0

The received name allows you yo detect the config descriptor to e.g. search for a special HID device type:

err = KS_execUsbCommand(
        deviceNameBuf,           // Device name
        KS_USB_GET_CONFIG_DESCRIPTOR,
        0,                       // Index of descriptors
        pBuf,                    // Puffer
        64000,                   // Puffer size
        KSF_ALTERNATIVE);        // Flags

An existing driver can be replaced:

strcpy(infPath+GetSystemDirectory(infPath,256),"\\Kdemo.inf");
err = KS_updateDriver(
        deviceNameBuf,           // Device name
        infPath,                 // INF-file
        0);                      // Flags, here 0

The founded device can be openend. If it is known, you can directly declare it as the device name:

err = KS_openUsbDevice(
        &hDevice,                // Address of handle
        "USB\\VID_10CF&PID_5500",// Device name
        0);                      // Flags, here 0

The essentially communication takes place via so-called Endpoints. There are up to 15 send and 15 receive endpoints for every device:

err = KS_getUsbPort(
        hDevice,                 // Device handle
        &hPort,                  // Address of handle
        endpointAddress,         // Number of Endpoints
        KSF_INTERRUPT_TRANSFER); // Flags: transfer mode

The communication takes place like the serial communication in the Serial Module.

If you have created a callback function (note Kernel Module), you can announce this as timer callback:

const int ms = 10000;            // Miliseconds
err = KS_createTimer(
        &hTimer,                 // Address of handle
        period * ms,             // Timerperiod in 100 ns
        hTimerCallBack,          // Callback handle
        KSF_DONT_START);         // Flags: not started yet

The Timer can be started for an cyclical execution:

err = KS_startTimer(
        hTimer,                  // Timer handle
        0,                       // Flags, here 0
        period * ms);            // Timer period in 100 ns

…und and stopable at anytime:

err = KS_stopTimer(
        hTimer);                 // Timer handle

…or starting again, e.g. for once call:

err = KS_startTimer(
        hTimer,                  // Timer handle
        KSF_ONE_SHOT,            // Flags, once
        period * ms);            // Timer period in 100 ns

A running timer can be aborted everytime, by a reason of this is it suitable for watchdog applications:

err = KS_cancelTimer(
        hTimer);                 // Timer handle

In this case starts the waiting time for cyclical timer again:

If you have created a callback function (note Kernel Module), you can announce this as timer callback:

const int ms = 10000;            // Miliseconds
err = KS_createTimer(
        &hTimer,                 // Address of handle
        period * ms,             // Timerperiod in 100 ns
        hTimerCallBack,          // Callback handle
        KSF_DONT_START);         // Flags: not started yet

The Timer can be started for an cyclical execution:

err = KS_startTimer(
        hTimer,                  // Timer handle
        0,                       // Flags, here 0
        period * ms);            // Timer period in 100 ns

…und and stopable at anytime:

err = KS_stopTimer(
        hTimer);                 // Timer handle

…or starting again, e.g. for once call:

err = KS_startTimer(
        hTimer,                  // Timer handle
        KSF_ONE_SHOT,            // Flags, once
        period * ms);            // Timer period in 100 ns

A running timer can be aborted everytime, by a reason of this is it suitable for Watchdog applications:

err = KS_cancelTimer(
        hTimer);                 // Timer handle

For using this timer on kernel level in real-time, the hardware timer has to be initialised:

const int us = 10;               // Microseconds
err = KS_setTimerResolution(
        resolution * us,         // Timer period in 100 ns
        KSF_HIGH_PRECISION);     // Flags, here high prec.

NEU! By now, it is possible to use the high precision mode on APIC systems.

The real-time timer can be announced:

err = KS_createTimer(
        &hTimer,                 // Address of handle
        period * us,             // Timer period in 100 ns
        hTimerCallBack,          // Callback handle
        KSF_REALTIME_EXEC);      // Flags: real-time timer

Therewith jitter is almost avioded!

At first, we have to activate the real-time environment (note RealTime Module). Afterwards we can create tasks:

err = KS_createTask(
        &hTask,                  // Address of handle
        hCallBack,               // Callback handle
        250,                     // Priority step (64 255)
        KSF_DONT_START);         // Flags, not started yet

The flag KSF_DONT_START declares the task to do not start – it is suspended. Starting is like the following:

err = KS_resumeTask(
        hTask);                  // Task handle

If you want to hinder the execution you can suspend it again:

err = KS_suspendTask(
        hTask);                  // Task handle

If a task shall interrupt by its own ( to get executed by another later), is it possible to call this function:

err = KS_suspendTask(
        NULL);                   // This task

The task can be directly started as Timer-Task:

err = KS_createTimer(
        &hTimer,                 // Address of handle
        50 * us,                 // Timer period in 100 ns
        hTask,                   // Handle of timer task
        KSF_REALTIME_EXEC);      // Flags, real-time execution

Now, the task will be circular activated with a period of 50 µs (20 kHz) in each timer clock.

If you want to end the task, you can call this function everytime:

err = KS_exitTask(
        exitCode);               // End-value of task

At first, the network adapter will be opened and the hardware id has to be entered:

err = KS_openAdapter(
        &hAdapter,               // Address of handle
        "VEN8086&DEV1226",       // Hardware id of adapter
        100,                     // RecvPool length
        100,                     // SendPool length
        0);                      // Flags, hier 0

If you want to send, you have to request a packet out of the pool and fill it:

err = KS_requestPacket(
        hAdapter,                // Adapter handle
        &pPacket,                // Pointer on Ethernet packet
        KSF_IP_PACKET);          // Flags, here IP packet
...                              // Filling packet
err = KS_sendPacket(
        hAdapter,                // Adapter handle
        pPacket,                 // Address of Ethernet packet
        KSF_IP_PACKET);          // Flags, here IP packet

The sequence of receiving is inverted: at first, a packet will be called and deallocated after analysis:

err = KS_recvPacket(
        hAdapter,                // Adapter handle
        &pPacket,                // Pointer on Ethernet packet
        KSF_IP_PACKET);          // Flags, here IP packet
...                              // Packet reading
err = KS_releasePacket(
        hAdapter,                // Adapter handle
        pPacket,                 // Address of Ethernet packets
        KSF_IP_PACKET);          // Flags, here IP packet

You also can register a callback function as real-time receive:

err = KS_installPacketHandler(
        hAdapter,                // Adapter handle
        KS_PACKET_RECV,          // Executing on packet receiving
        hRecvCallback,           // Handle of callback object
        0);                      // Flags, here 0

The opportunities of Packet Fast Modules are also available here. Additionally, Gigabit Ethernet controller will be supported (note Hardware compatibility list).

At first, the network adapter will be opened and the hardware ID has to be entered:

err = KS_openAdapter(
        &hAdapter,               // Address of handle
        "VEN8086&DEV1226",       // Hardware ID of adapter
        100,                     // RecvPool Length
        100,                     // SendPool Length
        0);                      // Flags, hier 0

If you want to send, you have to request a packet out of the pool and fill it:

err = KS_requestPacket(
        hAdapter,                // Adapter handle
        &pPacket,                // Pointer on Ethernet packet
        KSF_IP_PACKET);          // Flags, here IP packet
...                              // Filling packet
err = KS_sendPacket(
        hAdapter,                // Adapter handle
        pPacket,                 // Address of Ethernet packet
        KSF_IP_PACKET);          // Flags, here IP packet

The sequence of receiving is inverted: at first, a packet will be called and deallocated after analysis:

err = KS_recvPacket(
        hAdapter,                // Adapter handle
        &pPacket,                // Pointer on Ethernet packet
        KSF_IP_PACKET);          // Flags, here IP packet
...                              // Packet reading
err = KS_releasePacket(
        hAdapter,                // Adapter handle
        pPacket,                 // Address of Ethernet packets
        KSF_IP_PACKET);          // Flags, here IP packet

You also can register a callback function as real-time receive:

err = KS_installPacketHandler(
        hAdapter,                // Adapter handle
        KS_PACKET_RECV,          // Executing on packet receiving
        hRecvCallback,           // Handle of callback object
        0);                      // Flags, here 0

At first, the network connection has to be opened (note Packet Module). Therewith the EtherCAT-Master will be opened:

err = KS_openEcatMaster(
        &hMaster,                // Address of handle
        hAdapter,                // Network adapter handle 
        &pMasterDescApp,         // Master Descriptor (Application)
        &pMasterDescSys, 0);     // Master Descriptor (kernel)

The descriptor structure describes the EtherCAT topologie completely:

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

For the process data exchange it is necessary to create a dataset:

err = KS_createDataSet(
        &hDataset, 0);           // Address of handle

This dataset gets the desired slaves (e.g. I/O-clamps) or process data objects:

err = KS_assignDataSet(
        hDataset,                // Dataset handle
        NULL, NULL, NULL,        // Object addresses
        pMasterDescApp->slaves[slaveIndex], 0); // Descriptor

Here it is possible to return the already used memory addresses of variables. Also service data objects (SDO) can be written or read , e.g. the conversion sector of a analog input clamp:

err = KS_postDataObj(
        pMasterDescApp->slaves[sdo4],       // SDO-Descriptor
        pDataBuffer, 0);         // Writing data

Now, we want to change the state to start the process data exchage:

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

For the circular process data exchange, you may do a calculation in a real-time timer function and you send the desired data to the slaves:

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

The data transfer to the slaves takes place in the background. In the next timer clock, the received data will be applied on the dataset:

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

The access to the particular variables is enabled with KS_readDataObj or directly via the addresses in shared memory, which are saved in the descriptor.

See Features page! More info coming soon!