Kithara »Driver Collection«

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: