Windows Drivers and wRTOS Subsystem Startup/Shutdown

In this topic:

 

Startup Requirements

The wRTOS Subsystem must be loaded before any Windows driver can use the wRTOS RTKAPI. The RtkRtssAttachEx or RtkRtssAttach function do not automatically start the subsystem. The call to RtkRtssAttach or RtkRtssAttachEx is usually made at, but not restricted to, driver entry, unless your driver is set to start at boot time. If the Windows device driver caller starts at boot time, you must do the following:

  1. Configure the wRTOS Subsystem to start at boot time.
  2. Set your driver dependencies to depend on wRTOS Subsystem (wRTOS_Rtss.sys). For information on setting dependencies, see the MSDN article at https://learn.microsoft.com/en-us/windows-hardware/drivers/install/specifying-driver-load-order
  3. Call RtkRtssAttachEx or RtkRtssAttach ONCE in the Driver Dispatch routine, and NEVER in the DriverEntry routine.

Note: You should always prefer RtkRtssAttachEx over RtkRtssAttach as the former allows to pass a shutdown callback routine.

Overview of the Shutdown Handling

When the Subsystem begins to shut down, it loops through all the attached Windows drivers and, for each of them, it:

  1. Calls the Shutdown callback routine of the Windows driver (if one was passed in the call to RtkRtssAttachEx), at PASSIVE level
  2. Detaches the Windows driver (same effect as if the driver had called RtkRtssDetach)

Shutdown Callback Routine

This function must terminate all the operations that require the use of the RTK API.

Syntax

Copy 
VOID Routine(PVOID Context, LONG Reason)

Parameters

[in] Context

The value supplied in the call to RtkRtssAttachEx.

[in] Reason

One of the following values:

Value

Meaning

SHTDN_REASON_WINDOWS_SYSTEM_SHUTDOWN

The system is starting a normal shutdown. Shortly after all shutdown handlers have been executed, Windows will stop.

SHTDN_REASON_RTX_SYSTEM_SHUTDOWN

The Subsystem is going to be stopped (i.e., wRTOS is going to be unloaded). RTSS will continue to operate with service restrictions.

Remarks

The shutdown callback routine is always called at PASSIVE level.

The driver writer should use this callback function to close all the wRTOS handles created or opened previously. After this function returns, the RTK driver shall never make any further RTKAPI calls (otherwise it may freeze and/or crash Windows).

If needed, the shutdown callback routine can wait for some operations that still need RTKAPIs to be finished.

Note: When the system stops not in a normal shutdown where the reason argument is SHTDN_REASON_WINDOWS_STOP (i.e., blue screen or stop screen), the call back function is not called.

See Also