RtkIPC

Note: The RtkIPC sample does not support Windows 11 WDK (versions 22000 and above).

Description

This sample demonstrates usage of the Real-Time Kernel (RTK) API and how to synchronize a Windows driver with a wRTOS process. The RTK API is analogous to the existing wRTOS Real-Time (RT) API Inter-process communication (IPC) calls used within a Windows user mode application, but can be used by Windows kernel drivers. This example will demonstrate how to set up a Windows kernel driver so that it can access RTSS mutexes, events, semaphores, and shared memory.

This sample contains 3 projects for supported versions of Visual Studio.They are located under %public%\Public Documents\IntervalZero\MaxRT\wRTOS SDK\1.0\Samples\RtkIPC:

RtkIPCDrv – a wRTOS RTK API-enabled Windows kernel mode driver. This driver sets up 4 threads, each set up to use mutex, event, semaphore, and shared memory objects for inter-process communication. Each thread performs inter-process communication via shared memory and also performs mutex, event or semaphore based synchronizations to parse the shared memory contents.
RtkRtssApp – a wRTOS RTSS application used to communicate with the Windows driver RtkIPCDrv through inter-process communication mechanisms using shared memory and mutex, event, or semaphore synchronization objects.
RtkWinApp – a Windows console application that interfaces with the RTK enabled kernel mode driver.

Source Files

File	Description
`RtkIPCDrv.sys`	Windows system file.
`RtkIPCDrv.c`	Source file containing DriverEntry, which sets up threads to perform inter-process communication.
`Thread.c`	Source file containing implementation of various thread handlers using RTKAPI to perform inter-process communication.
`RtkRtssApp.rtss`	RTSS file.
`RtkRtssApp.c`	Source file containing usage of RTAPI functions similar to what the RTKAPI functions use to perform Windows driver inter-process communication.
`RtkIPCApp.exe`	Windows executable file.
`RtkIPCApp.c`	Source file for a Windows console application that interfaces with `RtkIpcDrv.sys` and controls the startup and shutdown of the driver.

Instructions for Building and Setting up the RtkAPI Sample

Note: The driver in this sample must be built using the Windows Driver Kit (WDK) 10 1803.

Launch Visual Studio and open the RtkIPC sample solution for your version of Visual Studio. For example, RtkIPC_VS2019.sln.
Build the RtkIPCDrv.sys binary.
Verify that RtkIPCDrv.sys was built without any errors.
To load RtkIPCDrv.sys, make sure it is signed or disable signing.
Install the driver using InstallDriver.bat.

Build RtkRtssApp.rtss
Build RtkWinApp.exe

Note: If you encounter errors relating to headers and libs while building RTK drivers, ensure that the installed versions of the WDK and Windows SDK match, and also ensure that the Target Platform Version setting in Visual Studio (Configuration Properties > General > Target Platform Version) is set to the correct version number.

Running RtkAPISample

Start the Subsystem.
Launch a Command Prompt as Administrator and navigate to the RtkIpcSample folder.
Type ”RunWinApp start” to load RtkIpcDrv.sys.
Run the test by issuing the following commands:
To test mutex access, type “RunWinApp mutex”
To test event access, type “RunWinApp event”
To test semaphore access, type “RunWinApp semaphore”
To test shared memory, type "RunWinApp shmem"
Depending on the type of test you are running, you should see feedback from both the Windows driver and RtkRtssApp.rtss.
After the test is complete, you may unload the Windows driver by typing “RunWinApp stop”.

IMPORTANT: Stopping the Subsystem is not sufficient to unload the driver. The driver requires the Subsystem to be running to completely stop itself. The Subsystem cannot be reloaded until it is completely unloaded. For this reason, step 6 must be completed before the Subsystem is stopped or else a restart will be required before the Subsystem can be started again.

Examples

The following examples demonstrate Windows kernel driver inter-process communication.

Example 1: Windows Kernel driver inter-process communication using Mutex

Command Prompt

> RunWinApp.bat mutex

CreateFile SUCCESS

Mutex Test: requestedNo = 0

Mutex Test: Return Message: PerformMutexTest: PASS. TotalErrors = 0 ***

Output

*** RtkApi Mutex Test: Test begins ***

RtOpenSharedMemory succeeded handle 100052, addr 0x62a62010

RtOpenMutex() Success

i = 0, sharedCount = 1

...

...

i = 99, sharedCount = 199

RtkApi Mutex Test: PASS

Example 2: Windows Kernel driver inter-process communication using Shared Memory

Command Prompt

> RunWinApp.bat shmem

CreateFile SUCCESS

SharedMemory Test: requestedNo = 0

SharedMemory Test: Return Message: PerformSharedMemoryTest: PASS. TotalErrors = 0 ***

Output

*** RtkApi SharedMemory: Test begins ***

RtOpenSharedMemory succeeded handle 100052, addr 0x62a62010

RtOpenMutex() success

RtkApi SharedMemory: PASS

APIs Referenced