windows-nt-4.0/private/ntos/dll/dllssstb.c

/*++

Copyright (c) 1989  Microsoft Corporation

Module Name:

    dllssstb.c

Abstract:

    Debug Subsystem DbgSs API Stubs

Author:

    Mark Lucovsky (markl) 22-Jan-1990

Revision History:

--*/

#include "dbgdllp.h"
#include "ldrp.h"

NTSTATUS
DbgSspConnectToDbg( VOID )

/*++

Routine Description:

    This routine makes a connection between the caller and the
    DbgSs port in the Dbg subsystem.

Arguments:

    None.

Return Value:

    TBD.

--*/

{
    NTSTATUS st;
    UNICODE_STRING PortName;
    SECURITY_QUALITY_OF_SERVICE DynamicQos;

    //
    // Set up the security quality of service parameters to use over the
    // port.  Use the most efficient (least overhead) - which is dynamic
    // rather than static tracking.
    //

    DynamicQos.ImpersonationLevel = SecurityImpersonation;
    DynamicQos.ContextTrackingMode = SECURITY_DYNAMIC_TRACKING;
    DynamicQos.EffectiveOnly = TRUE;


    RtlInitUnicodeString(&PortName,L"\\DbgSsApiPort");
    st = NtConnectPort(
            &DbgSspApiPort,
            &PortName,
            &DynamicQos,
            NULL,
            NULL,
            NULL,
            NULL,
            0L
            );

    return st;

}

NTSTATUS
DbgSspException (
    IN PDBGSS_CONTINUE_KEY ContinueKey,
    IN PCLIENT_ID AppClientId,
    IN PDBGKM_EXCEPTION Exception
    )

/*++

Routine Description:

    This function is called by emulation subsystems to report that
    an exception occured in a thread.

Arguments:

    ContinueKey - Supplies the captured DbgKm API message that needs a reply
        should this API complete successfully.

    AppClientId - Supplies the address of the ClientId of the thread that
        encountered an exception.

    Exception - Supplies the address of the Exception message as sent
        through the applications DebugPort.

Return Value:

    TBD

--*/

{

    NTSTATUS st;
    DBGSS_APIMSG ApiMsg;

    PDBGKM_EXCEPTION args;

    args = &ApiMsg.u.Exception;

    DBGSS_FORMAT_API_MSG(ApiMsg,DbgSsExceptionApi,sizeof(*args),AppClientId,ContinueKey);

    *args = *Exception;

    st = NtRequestPort(DbgSspApiPort, (PPORT_MESSAGE) &ApiMsg);

    return st;
}

NTSTATUS
DbgSspCreateThread (
    IN PDBGSS_CONTINUE_KEY ContinueKey,
    IN PCLIENT_ID AppClientId,
    IN PDBGKM_CREATE_THREAD NewThread
    )

/*++

Routine Description:

    This function is called by emulation subsystems to report the
    creation of a new thread to the Dbg subsystem.

Arguments:

    ContinueKey - Supplies the captured DbgKm API message that needs a reply
        should this API complete successfully.

    AppClientId - Supplies the address of the new thread's ClientId.

    NewThread - Supplies the address of the NewThread message as sent through
        the applications DebugPort. The calling subsystem may modify the
        SubSystemKey field of this message.

Return Value:

    TBD

--*/

{

    NTSTATUS st;
    DBGSS_APIMSG ApiMsg;

    PDBGKM_CREATE_THREAD args;

    args = &ApiMsg.u.CreateThread;

    DBGSS_FORMAT_API_MSG(ApiMsg,DbgSsCreateThreadApi,sizeof(*args),AppClientId, ContinueKey);

    *args = *NewThread;

    st = NtRequestPort(DbgSspApiPort, (PPORT_MESSAGE) &ApiMsg);

    return st;
}


NTSTATUS
DbgSspCreateProcess (
    IN PDBGSS_CONTINUE_KEY ContinueKey,
    IN PCLIENT_ID AppClientId,
    IN PCLIENT_ID DebugUiClientId,
    IN PDBGKM_CREATE_PROCESS NewProcess
    )

/*++

Routine Description:

    This function is called by emulation subsystems to report the
    creation of a new process to the Dbg subsystem.  It is the
    responsibility of individual subsystems to track a process and its
    controlling DebugUi.

Arguments:

    ContinueKey - Supplies the captured DbgKm API message that needs a reply
        should this API complete successfully.

    AppClientId - Supplies the address of the new thread's ClientId.

    DebugUiClientId - Supplies the address of the ClientId of the user
        interface controlling the new thread.

    NewProcess - Supplies the address of the NewProcess message as sent through
        the applications DebugPort. The calling subsystem may modify the
        SubSystemKey fields of this message.

Return Value:

    TBD

--*/

{

    NTSTATUS st;
    DBGSS_APIMSG ApiMsg;

    PDBGSS_CREATE_PROCESS args;

    args = &ApiMsg.u.CreateProcessInfo;

    DBGSS_FORMAT_API_MSG(ApiMsg,DbgSsCreateProcessApi,sizeof(*args),AppClientId,ContinueKey);

    args->DebugUiClientId = *DebugUiClientId;
    args->NewProcess = *NewProcess;

    st = NtRequestPort(DbgSspApiPort, (PPORT_MESSAGE) &ApiMsg);

    return st;

}

NTSTATUS
DbgSspExitThread (
    IN PDBGSS_CONTINUE_KEY ContinueKey,
    IN PCLIENT_ID AppClientId,
    IN PDBGKM_EXIT_THREAD ExitThread
    )

/*++

Routine Description:

    This function is called by emulation subsystems to report that
    a thread is exiting.

Arguments:

    ContinueKey - Supplies the captured DbgKm API message that needs a reply
        should this API complete successfully.

    AppClientId - Supplies the address of the exiting thread's ClientId.

    ExitThread - Supplies the address of the ExitThread message as sent
        through the applications DebugPort.

Return Value:

    TBD

--*/

{

    NTSTATUS st;
    DBGSS_APIMSG ApiMsg;

    PDBGKM_EXIT_THREAD args;

    args = &ApiMsg.u.ExitThread;

    DBGSS_FORMAT_API_MSG(ApiMsg,DbgSsExitThreadApi,sizeof(*args),AppClientId,ContinueKey);

    *args = *ExitThread;

    st = NtRequestPort(DbgSspApiPort, (PPORT_MESSAGE) &ApiMsg);

    return st;
}

NTSTATUS
DbgSspExitProcess (
    IN PDBGSS_CONTINUE_KEY ContinueKey,
    IN PCLIENT_ID AppClientId,
    IN PDBGKM_EXIT_PROCESS ExitProcess
    )

/*++

Routine Description:

    This function is called by emulation subsystems to report that
    a process is exiting.

Arguments:

    ContinueKey - Supplies the captured DbgKm API message that needs a reply
        should this API complete successfully.

    AppClientId - Supplies the address of the ClientId of the last thread
        in the process to exit.

    ExitProcess - Supplies the address of the ExitProcess message as sent
        through the applications DebugPort.

Return Value:

    TBD

--*/

{

    NTSTATUS st;
    DBGSS_APIMSG ApiMsg;

    PDBGKM_EXIT_PROCESS args;

    args = &ApiMsg.u.ExitProcess;

    DBGSS_FORMAT_API_MSG(ApiMsg,DbgSsExitProcessApi,sizeof(*args),AppClientId,ContinueKey);

    *args = *ExitProcess;

    st = NtRequestPort(DbgSspApiPort, (PPORT_MESSAGE) &ApiMsg);

    return st;
}

NTSTATUS
DbgSspLoadDll (
    IN PDBGSS_CONTINUE_KEY ContinueKey,
    IN PCLIENT_ID AppClientId,
    IN PDBGKM_LOAD_DLL LoadDll
    )

/*++

Routine Description:

    This function is called by emulation subsystems to report that
    a a process has loaded a DLL

Arguments:

    ContinueKey - Supplies the captured DbgKm API message that needs a reply
        should this API complete successfully.

    AppClientId - Supplies the address of the ClientId of the thread
        that mapped the section.

    LoadDll - Supplies the address of the LoadDll message as sent
        through the applications DebugPort.

Return Value:

    TBD

--*/

{

    NTSTATUS st;
    DBGSS_APIMSG ApiMsg;

    PDBGKM_LOAD_DLL args;

    args = &ApiMsg.u.LoadDll;

    DBGSS_FORMAT_API_MSG(ApiMsg,DbgSsLoadDllApi,sizeof(*args),AppClientId,ContinueKey);

    *args = *LoadDll;

    st = NtRequestPort(DbgSspApiPort, (PPORT_MESSAGE) &ApiMsg);

    return st;
}

NTSTATUS
DbgSspUnloadDll (
    IN PDBGSS_CONTINUE_KEY ContinueKey,
    IN PCLIENT_ID AppClientId,
    IN PDBGKM_UNLOAD_DLL UnloadDll
    )

/*++

Routine Description:

    This function is called by emulation subsystems to report that
    a a process has un-mapped a view of a section

Arguments:

    ContinueKey - Supplies the captured DbgKm API message that needs a reply
        should this API complete successfully.

    AppClientId - Supplies the address of the ClientId of the thread
        that mapped the section.

    UnloadDll - Supplies the address of the UnloadDll message as sent
        through the applications DebugPort.

Return Value:

    TBD

--*/

{

    NTSTATUS st;
    DBGSS_APIMSG ApiMsg;

    PDBGKM_UNLOAD_DLL args;

    args = &ApiMsg.u.UnloadDll;

    DBGSS_FORMAT_API_MSG(ApiMsg,DbgSsUnloadDllApi,sizeof(*args),AppClientId,ContinueKey);

    *args = *UnloadDll;

    st = NtRequestPort(DbgSspApiPort, (PPORT_MESSAGE) &ApiMsg);

    return st;
}


NTSTATUS
DbgSsInitialize(
    IN HANDLE KmReplyPort,
    IN PDBGSS_UI_LOOKUP UiLookUpRoutine,
    IN PDBGSS_SUBSYSTEMKEY_LOOKUP SubsystemKeyLookupRoutine OPTIONAL,
    IN PDBGSS_DBGKM_APIMSG_FILTER KmApiMsgFilter OPTIONAL
    )

/*++

Routine Description:

    This function is called by a subsystem to initialize
    portions of the debug subsystem dll. The main purpose of
    this function is to set up callouts that are needed in order
    to use DbgSsHandleKmApiMsg, and to connect to the debug server.

Arguments:

    KmReplyPort - Supplies a handle to the port that the subsystem
        receives DbgKm API messages on.

    UiLookupRoutine - Supplies the address of a function that will
        be called upon receipt of a process creation message. The
        purpose of this function is to identify the client id of the
        debug ui controlling the process.

    SubsystemKeyLookupRoutine - Supplies the address of a function that
        will be called upon receipt of process creation and thread
        creation messages.  The purpose of this function is to allow a
        subsystem to correlate a key value with a given process or
        thread.

    KmApiMsgFilter - Supplies the address of a function that will be
        called upon receipt of a DbgKm Api message. This function can
        take any action. If it returns any value other than DBG_CONTINUE,
        DbgSsHandleKmApiMsg will not process the message. This function
        is called before any other call outs occur.

Return Value:

    Return code of DbgSsConnectToDbg.

--*/

{
    NTSTATUS st;

    st = DbgSspConnectToDbg();

    if (NT_SUCCESS(st)) {
        DbgSspKmReplyPort = KmReplyPort;
        DbgSspUiLookUpRoutine = UiLookUpRoutine;
        DbgSspSubsystemKeyLookupRoutine = SubsystemKeyLookupRoutine;
        DbgSspKmApiMsgFilter = KmApiMsgFilter;

        st = RtlCreateUserThread(
                NtCurrentProcess(),
                NULL,
                FALSE,
                0L,
                0L,
                0L,
                DbgSspSrvApiLoop,
                NULL,
                NULL,
                NULL
                );
        ASSERT( NT_SUCCESS(st) );
    }

    return st;
}


#if DBG
PSZ DbgpKmApiName[ DbgKmMaxApiNumber+1 ] = {
    "DbgKmException",
    "DbgKmCreateThread",
    "DbgKmCreateProcess",
    "DbgKmExitThread",
    "DbgKmExitProcess",
    "DbgKmLoadDll",
    "DbgKmUnloadDll",
    "Unknown DbgKm Api Number"
};
#endif // DBG

VOID
DbgSsHandleKmApiMsg(
    IN PDBGKM_APIMSG ApiMsg,
    IN HANDLE ReplyEvent OPTIONAL
    )

/*++

Routine Description:

    This function is called by a subsystem upon receipt of a message whose
    type is LPC_DEBUG_EVENT. The purpose of this function is to propagate
    the debug event message to the debug server.

    A number of callouts are performed prior to propagating the message:

      - For all messages, the KmApiMsgFilter is called (if it was
        supplied during DbgSsInitialize.  If this returns anything other
        that DBG_CONTINUE, the message is not propagated by this
        function.  The caller is responsible for event propagation, and
        for replying to the thread reporting the debug event.

      - For create process messages, the UiLookupRoutine is called.  If
        a success code is returned than message is propagated.
        Otherwise, a reply is generated to the thread reporting the
        debug event.

     -  For create process and create thread messages,
        SubsystemKeyLookupRoutine is called.  Failure does not effect
        propagation.  It simply inhibits the update of messages
        SubSystemKey field.

    Based on the debug event type, a DBGSS_APIMSG is formated and sent
    as a datagram to the debug server.

Arguments:

    ApiMsg - Supplies the debug event message to propagate to the debug
        server.

    ReplyEvent - An optional parameter, that if specified supplies a handle
        to an event that is to be signaled rather that generating a reply
        to this message.

Return Value:

    None.

--*/


{
    NTSTATUS st;
    CLIENT_ID DebugUiClientId;
    ULONG SubsystemKey;
    PDBGSS_CONTINUE_KEY ContinueKey;

    ApiMsg->ReturnedStatus = STATUS_PENDING;

#if DBG && 0
    if (ApiMsg->ApiNumber >= DbgKmMaxApiNumber ) {
        ApiMsg->ApiNumber = DbgKmMaxApiNumber;
    }
    DbgPrint( "DBG:  %s Api Request received from %lx.%lx\n",
              DbgpKmApiName[ ApiMsg->ApiNumber ],
              ApiMsg->h.ClientId.UniqueProcess,
              ApiMsg->h.ClientId.UniqueThread
           );
#endif // DBG

    if (DbgSspKmApiMsgFilter) {
        if ( (DbgSspKmApiMsgFilter)(ApiMsg) != DBG_CONTINUE ) {
            return;
        }
    }

    ContinueKey = (PDBGSS_CONTINUE_KEY) RtlAllocateHeap(RtlProcessHeap(), MAKE_TAG( DBG_TAG ), sizeof(*ContinueKey));
    if ( !ContinueKey ) {
        ApiMsg->ReturnedStatus = STATUS_NO_MEMORY;
        if ( ARGUMENT_PRESENT(ReplyEvent) ) {
            st = NtSetEvent(ReplyEvent,NULL);
        } else {
            st = NtReplyPort(DbgSspKmReplyPort,
                             (PPORT_MESSAGE)ApiMsg
                            );
        }
        ASSERT(NT_SUCCESS(st));
        return;
    }
    ContinueKey->KmApiMsg = *ApiMsg;

    ContinueKey->ReplyEvent = ReplyEvent;

    switch (ApiMsg->ApiNumber) {

    case DbgKmExceptionApi :
        st = DbgSspException(
                ContinueKey,
                &ApiMsg->h.ClientId,
                &ApiMsg->u.Exception
                );

        break;

    case DbgKmCreateThreadApi :

        if ( DbgSspSubsystemKeyLookupRoutine ) {

            st = (DbgSspSubsystemKeyLookupRoutine)(
                    &ApiMsg->h.ClientId,
                    &SubsystemKey,
                    FALSE
                    );

            if ( NT_SUCCESS(st) ) {
                ApiMsg->u.CreateThread.SubSystemKey = SubsystemKey;
            }
        }

        st = DbgSspCreateThread(
                ContinueKey,
                &ApiMsg->h.ClientId,
                &ApiMsg->u.CreateThread
                );

        break;

    case DbgKmCreateProcessApi :

        st = (DbgSspUiLookUpRoutine)(
                &ApiMsg->h.ClientId,
                &DebugUiClientId
                );
        if ( !NT_SUCCESS(st) ) {
            break;
        }

        if ( DbgSspSubsystemKeyLookupRoutine ) {

            st = (DbgSspSubsystemKeyLookupRoutine)(
                    &ApiMsg->h.ClientId,
                    &SubsystemKey,
                    TRUE
                    );

            if ( NT_SUCCESS(st) ) {
                ApiMsg->u.CreateProcessInfo.SubSystemKey = SubsystemKey;
            }

            st = (DbgSspSubsystemKeyLookupRoutine)(
                    &ApiMsg->h.ClientId,
                    &SubsystemKey,
                    FALSE
                    );

            if ( NT_SUCCESS(st) ) {
                ApiMsg->u.CreateProcessInfo.InitialThread.SubSystemKey = SubsystemKey;
            }
        }

        st = DbgSspCreateProcess(
                ContinueKey,
                &ApiMsg->h.ClientId,
                &DebugUiClientId,
                &ApiMsg->u.CreateProcessInfo
                );
        break;


    case DbgKmExitThreadApi :
        st = DbgSspExitThread(
                ContinueKey,
                &ApiMsg->h.ClientId,
                &ApiMsg->u.ExitThread
                );
        break;

    case DbgKmExitProcessApi :
        st = DbgSspExitProcess(
                ContinueKey,
                &ApiMsg->h.ClientId,
                &ApiMsg->u.ExitProcess
                );
        break;

    case DbgKmLoadDllApi :
        st = DbgSspLoadDll(
                ContinueKey,
                &ApiMsg->h.ClientId,
                &ApiMsg->u.LoadDll
                );
        break;

    case DbgKmUnloadDllApi :
        st = DbgSspUnloadDll(
                ContinueKey,
                &ApiMsg->h.ClientId,
                &ApiMsg->u.UnloadDll
                );
        break;

    default :
        st = STATUS_NOT_IMPLEMENTED;
    }

    if ( !NT_SUCCESS(st) ) {
        ApiMsg->ReturnedStatus = st;
        RtlFreeHeap(RtlProcessHeap(), 0, ContinueKey);
        if ( ARGUMENT_PRESENT(ReplyEvent) ) {
            st = NtSetEvent(ReplyEvent,NULL);
        } else {
            st = NtReplyPort(DbgSspKmReplyPort,
                             (PPORT_MESSAGE)ApiMsg
                            );
        }
        ASSERT(NT_SUCCESS(st));
    }
}


NTSTATUS
DbgSspSrvApiLoop(
    IN PVOID ThreadParameter
    )

/*++

Routine Description:

    This loop services Dbg Subsystem server originated messages.

Arguments:

    ThreadParameter - Not used.

Return Value:

    None.

--*/

{
    DBGSRV_APIMSG DbgSrvApiMsg;
    PDBGSS_CONTINUE_KEY ContinueKey;
    NTSTATUS st;

    for(;;) {

        st = NtReplyWaitReceivePort(
                DbgSspApiPort,
                NULL,
                NULL,
                (PPORT_MESSAGE) &DbgSrvApiMsg
                );

        if (!NT_SUCCESS( st )) {
            DbgPrint( "DBGSS: NtReplyWaitReceivePort failed - Status == %x\n", st );
            DbgBreakPoint();
            continue;
            }

        ASSERT(DbgSrvApiMsg.ApiNumber < DbgSrvMaxApiNumber);

        switch (DbgSrvApiMsg.ApiNumber ) {
        case DbgSrvContinueApi :

            //
            // Might want to implement continue status based callout
            // like DBG_TERMINATE_PROCESS/THREAD
            //

            ContinueKey = (PDBGSS_CONTINUE_KEY) DbgSrvApiMsg.ContinueKey;
            ContinueKey->KmApiMsg.ReturnedStatus = DbgSrvApiMsg.ReturnedStatus;

            if ( ContinueKey->ReplyEvent ) {
                st = NtSetEvent(ContinueKey->ReplyEvent,NULL);
            } else {
                st = NtReplyPort(DbgSspKmReplyPort,
                                 (PPORT_MESSAGE) &ContinueKey->KmApiMsg
                                );
            }

            RtlFreeHeap(RtlProcessHeap(), 0, ContinueKey);
            break;
        default :
            ASSERT(FALSE);
        }
    }

    //
    // Make the compiler happy
    //

    return st;
}