RtkRtssAttachEx

RtkRtssAttachEx attaches a Windows 64 kernel device driver to the RTX64 Real-Time Subsystem and allows for setting up a callback function when the Subsystem is shut down.

Syntax

NTSTATUS RtkRtssAttachEx(
    ULONG MaxWFSO,
    PRTSSINST RtssInstPtr,
    VOID (RTKAPI *Routine) (PVOID Context, LONG reason), 
    PVOID Context,
);

Parameters

MaxWFSO

The count of the number of wait-for-single-objects the user requires. The required minimum is one.

RtssInstPtr

A pointer to a RTSSINST object that will return a non-zero value if the function succeeds, 0 if the function fails.

Routine

The call back function to be called when the RTX64 Subsystem is starting a normal stop, or system is starting a normal shutdown.

Context

The argument to the call back function.

Return Value

RtkRtssAttachEx returns STATUS_SUCCESS on success or on failure one of the following NTSTATUS error codes is possible:

• STATUS_UNSUCCESSFUL
• STATUS_INVALID_PARAMETER
• STATUS_LICENSE_VIOLATION

Remarks

This call should be made only once by a kernel-resident device driver. The returned instance must be used for all subsequent RTKAPI calls. This call is usually made at, but not restricted to, driver entry, unless your device driver is set to start at boot time.

If the device driver caller starts at boot time, you must:

1. Set the RTX64 Subsystem to start at the boot time.
2. Set your driver dependencies to depend on RTX Subsystem (Rtx_Rtss.sys). For information on setting dependencies, see the MSDN article at http://msdn.microsoft.com/en-us/library/windows/hardware/ff552319(v=vs.85).aspx
3. Make this call ONCE in the Driver Dispatch routine, NEVER in the DriverEntry() routine.

The reason arguments have the following values:

Argument	Value
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	RTX64 Subsystem is going to be stopped (i.e., RTX64 is going to be unloaded). RTSS will continue to operate with service restriction.

Driver writer should use this call back function to close all the RTX64 handles created or opened previously. After this function returns, the RTK driver should never make any further RTKAPI calls, since RTX64 has called RtkRtssDetach internally.

NOTE: When 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:

Windows Drivers and the RTX64 Subsystem Startup

RtkRtssDetach

RtkRtssAttach