Minoca-os/apps/debug/client/console.h

/*++

Copyright (c) 2012 Minoca Corp.

    This file is licensed under the terms of the GNU General Public License
    version 3. Alternative licensing terms are available. Contact
    info@minocacorp.com for details. See the LICENSE file at the root of this
    project for complete licensing information.

Module Name:

    console.h

Abstract:

    This header contains definitions for the generic console functions required
    by the debugger.

Author:

    Evan Green 2-Jul-2012

--*/

//
// ---------------------------------------------------------------- Definitions
//

#define KEY_RETURN     0x10
#define KEY_UP         0x01
#define KEY_DOWN       0x02
#define KEY_ESCAPE     0x03
#define KEY_REMOTE     0x04

//
// ------------------------------------------------------ Data Type Definitions
//

typedef
PVOID
(*PDBGR_THREAD_ROUTINE) (
    PVOID Parameter
    );

/*++

Routine Description:

    This routine is the entry point prototype for a new thread.

Arguments:

    Parameter - Supplies a pointer supplied by the creator of the thread.

Return Value:

    Returns a pointer value.

--*/

//
// -------------------------------------------------------- Function Prototypes
//

//
// Functions callable by the OS support layer.
//

INT
DbgrMain (
    INT ArgumentCount,
    CHAR **Arguments
    );

/*++

Routine Description:

    This routine is the main entry point for the debugger.

Arguments:

    ArgumentCount - Supplies the number of arguments on the command line.

    Arguments - Supplies an array of strings representing the arguments.

Return Value:

    Returns 0 on success, nonzero on failure.

--*/

VOID
DbgrRequestBreakIn (
    VOID
    );

/*++

Routine Description:

    This routine sends a break-in request to the target.

Arguments:

    None.

Return Value:

    None.

--*/

VOID
DbgrDisplayCommandLineProfilerData (
    PROFILER_DATA_TYPE DataType,
    PROFILER_DISPLAY_REQUEST DisplayRequest,
    ULONG Threshold
    );

/*++

Routine Description:

    This routine displays the profiler data collected by the core debugging
    infrastructure to standard out.

Arguments:

    DataType - Supplies the type of profiler data that is to be displayed.

    DisplayRequest - Supplies a value requesting a display action, which can
        either be to display data once, continually, or to stop continually
        displaying data.

    Threshold - Supplies the minimum percentage a stack entry hit must be in
        order to be displayed.

Return Value:

    None.

--*/

BOOL
DbgrGetProfilerStackData (
    PSTACK_DATA_ENTRY *StackTreeRoot
    );

/*++

Routine Description:

    This routine processes and returns any pending profiling stack data. It
    will add it to the provided stack tree root. The caller is responsible for
    destroying the tree.

Arguments:

    StackTreeRoot - Supplies a pointer to a pointer to the root of the stack
        data tree. Upon return from the routine it will be updated with all the
        newly parsed data. If the root is null, a new root will be allocated.

Return Value:

    Returns TRUE when data is successfully returned, or FALSE on failure.

--*/

VOID
DbgrDestroyProfilerStackData (
    PSTACK_DATA_ENTRY Root
    );

/*++

Routine Description:

    This routine destroys a profiler stack data tree.

Arguments:

    Root - Supplies a pointer to the root element of the tree.

Return Value:

    None.

--*/

VOID
DbgrPrintProfilerStackData (
    PSTACK_DATA_ENTRY Root,
    ULONG Threshold
    );

/*++

Routine Description:

    This routine prints profiler stack data to standard out.

Arguments:

    Root - Supplies a pointer to the root of the profiler stack data tree.

    Threshold - Supplies the minimum percentage a stack entry hit must be in
        order to be displayed.

Return Value:

    None.

--*/

VOID
DbgrProfilerStackEntrySelected (
    PSTACK_DATA_ENTRY Root
    );

/*++

Routine Description:

    This routine is called when a profiler stack data entry is selected by the
    user.

Arguments:

    Root - Supplies a pointer to the root of the profiler stack data tree.

Return Value:

    None.

--*/

BOOL
DbgrGetProfilerMemoryData (
    PLIST_ENTRY *MemoryPoolListHead
    );

/*++

Routine Description:

    This routine processes and returns any pending profiling memory data.

Arguments:

    MemoryPoolListHead - Supplies a pointer to head of the memory pool list
        that is to be populated with the most up to date pool data.

Return Value:

    Returns TRUE when data is successfully returned, or FALSE on failure.

--*/

VOID
DbgrDestroyProfilerMemoryData (
    PLIST_ENTRY PoolListHead
    );

/*++

Routine Description:

    This routine destroys a profiler memory data list.

Arguments:

    PoolListHead - Supplies a pointer to the head of the memory pool list
        that is to be destroyed.

Return Value:

    None.

--*/

VOID
DbgrPrintProfilerMemoryData (
    PLIST_ENTRY MemoryPoolListHead,
    BOOL DeltaMode,
    ULONG ActiveCountThreshold
    );

/*++

Routine Description:

    This routine prints the statistics from the given memory pool list to the
    debugger console.

Arguments:

    MemoryPoolListHead - Supplies a pointer to the head of the memory pool
        list.

    DeltaMode - Supplies a boolean indicating whether or not the memory pool
        list represents a delta from a previous point in time.

    ActiveCountThreshold - Supplies the active count threshold. No statistics
        will be displayed for tags with an active count less than this
        threshold.

Return Value:

    None.

--*/

PLIST_ENTRY
DbgrSubtractMemoryStatistics (
    PLIST_ENTRY CurrentListHead,
    PLIST_ENTRY BaseListHead
    );

/*++

Routine Description:

    This routine subtracts the given current memory list from the base memory
    list, returning a list that contains the deltas for memory pool statistics.
    If this routine ever fails, it just returns the current list.

Arguments:

    CurrentListHead - Supplies a pointer to the head of the current list of
        memory pool data.

    BaseListHead - supplies a pointer to the head of the base line memory list
        from which the deltas are created.

Return Value:

    Returns a new memory pool list if possible. If the routine fails or there
    is no base line, then the current memory list is returned.

--*/

//
// Functions implemented by the OS support layer.
//

BOOL
DbgrOsInitializeConsole (
    PBOOL EchoCommands
    );

/*++

Routine Description:

    This routine performs any initialization steps necessary before the console
    can be used.

Arguments:

    EchoCommands - Supplies a pointer where a boolean will be returned
        indicating if the debugger should echo commands received (TRUE) or if
        the console has already echoed the command (FALSE).

Return Value:

    Returns TRUE on success, FALSE on failure.

--*/

VOID
DbgrOsDestroyConsole (
    VOID
    );

/*++

Routine Description:

    This routine cleans up anything related to console functionality as a
    debugger is exiting.

Arguments:

    None.

Return Value:

    None.

--*/

INT
DbgrOsCreateThread (
    PDBGR_THREAD_ROUTINE ThreadRoutine,
    PVOID Parameter
    );

/*++

Routine Description:

    This routine creates a new thread.

Arguments:

    ThreadRoutine - Supplies a pointer to the routine to run in the new thread.
        The thread is destroyed when the supplied routine returns.

    Parameter - Supplies a pointer to a parameter to pass to the thread.

Return Value:

    0 on success.

    Returns an error code on failure.

--*/

int
DbgrOsCreatePipe (
    int FileDescriptors[2]
    );

/*++

Routine Description:

    This routine creates an anonymous pipe.

Arguments:

    FileDescriptors - Supplies a pointer where handles will be returned
        representing the read and write ends of the pipe.

Return Value:

    0 on success.

    -1 on failure. The errno variable will be set to indicate the error.

--*/

char *
DbgrOsGetUserName (
    void
    );

/*++

Routine Description:

    This routine returns the user name of the current process.

Arguments:

    None.

Return Value:

    Returns a pointer to a string containing the user name if it can be found.
    The caller should not free or modify this memory, and it may be reused on
    subsequent calls.

--*/

char *
DbgrOsGetHostName (
    void
    );

/*++

Routine Description:

    This routine returns the host name of the current machine.

Arguments:

    None.

Return Value:

    Returns a pointer to a string containing the user name if it can be found.
    The caller is responsible for freeing this memory.

--*/

VOID
DbgrOsPrepareToReadInput (
    VOID
    );

/*++

Routine Description:

    This routine is called before the debugger begins to read a line of input
    from the user.

Arguments:

    None.

Return Value:

    None.

--*/

BOOL
DbgrOsGetCharacter (
    PUCHAR Key,
    PUCHAR ControlKey
    );

/*++

Routine Description:

    This routine gets one character from the standard input console.

Arguments:

    Key - Supplies a pointer that receives the printable character. If this
        parameter is NULL, printing characters will be discarded from the input
        buffer.

    ControlKey - Supplies a pointer that receives the non-printable character.
        If this parameter is NULL, non-printing characters will be discarded
        from the input buffer.

Return Value:

    Returns TRUE on success, FALSE on failure.

--*/

VOID
DbgrOsRemoteInputAdded (
    VOID
    );

/*++

Routine Description:

    This routine is called after a remote command is received and placed on the
    standard input remote command list. It wakes up a thread blocked on local
    user input in an OS-dependent fashion.

Arguments:

    None.

Return Value:

    None.

--*/

VOID
DbgrOsPostInputCallback (
    VOID
    );

/*++

Routine Description:

    This routine is called after a line of input is read from the user, giving
    the OS specific code a chance to restore anything it did in the prepare
    to read input function.

Arguments:

    None.

Return Value:

    None.

--*/

BOOL
InitializeCommunications (
    PSTR Channel,
    ULONG Baudrate
    );

/*++

Routine Description:

    This routine initializes the communication medium the debugger uses to
    communicate with the target.

Arguments:

    Channel - Supplies a description of the communication medium.

    Baudrate - Supplies the baudrate to use for serial based communications.

Return Value:

    Returns TRUE on success, FALSE on failure.

--*/

VOID
DestroyCommunications (
    VOID
    );

/*++

Routine Description:

    This routine tears down the debug communication channel.

Arguments:

    None.

Return Value:

    None.

--*/

BOOL
CommReceive (
    PVOID Buffer,
    ULONG BytesToRead
    );

/*++

Routine Description:

    This routine receives a number of bytes from the debugger/debuggee
    connection.

Arguments:

    Buffer - Supplies a pointer to the buffer where the data should be returned.

    BytesToRead - Supplies the number of bytes that should be received into the
        buffer.

Return Value:

    Returns TRUE on success, FALSE on failure.

--*/

BOOL
CommSend (
    PVOID Buffer,
    ULONG BytesToSend
    );

/*++

Routine Description:

    This routine sends a number of bytes through the debugger/debuggee
    connection.

Arguments:

    Buffer - Supplies a pointer to the buffer where the data to be sent resides.

    BytesToSend - Supplies the number of bytes that should be sent.

Return Value:

    Returns TRUE on success, FALSE on failure.

--*/

BOOL
CommReceiveBytesReady (
    VOID
    );

/*++

Routine Description:

    This routine determines whether or not bytes can be read from the
    debugger connection.

Arguments:

    None.

Return Value:

    TRUE if there are bytes ready to be read.

    FALSE if no bytes are ready at this time.

--*/

VOID
CommStall (
    ULONG Milliseconds
    );

/*++

Routine Description:

    This routine pauses for the given amount of time.

Arguments:

    Milliseconds - Supplies the amount of time, in milliseconds, to stall the
        current thread for.

Return Value:

    None.

--*/

BOOL
UiLoadSourceFile (
    PSTR Path,
    PVOID Contents,
    ULONGLONG Size
    );

/*++

Routine Description:

    This routine loads the contents of a file into the source window.

Arguments:

    Path - Supplies the path of the file being loaded. If this is NULL, then
        the source window should be cleared.

    Contents - Supplies the source file data. This can be NULL.

    Size - Supplies the size of the source file data in bytes.

Return Value:

    Returns TRUE if there was no error, or FALSE if there was an error.

--*/

BOOL
UiHighlightExecutingLine (
    LONG LineNumber,
    BOOL Enable
    );

/*++

Routine Description:

    This routine highlights the currently executing source line and scrolls to
    it.

Arguments:

    LineNumber - Supplies the 1-based line number to highlight (ie the first
        line in the source file is line 1).

    Enable - Supplies a flag indicating whether to highlight this line (TRUE)
        or restore the line to its original color (FALSE).

Return Value:

    Returns TRUE if there was no error, or FALSE if there was an error.

--*/

VOID
UiEnableCommands (
    BOOL Enable
    );

/*++

Routine Description:

    This routine enables or disables the command edit control from being
    enabled. If disabled, the edit control will be made read only.

Arguments:

    Enable - Supplies a flag indicating whether or not to enable (TRUE) or
        disable (FALSE) the command box.

Return Value:

    None.

--*/

VOID
UiSetCommandText (
    PSTR Text
    );

/*++

Routine Description:

    This routine sets the text inside the command edit box.

Arguments:

    Text - Supplies a pointer to a null terminated string to set the command
        text to.

Return Value:

    None.

--*/

VOID
UiSetPromptText (
    PSTR Text
    );

/*++

Routine Description:

    This routine sets the text inside the prompt edit box.

Arguments:

    Text - Supplies a pointer to a null terminated string to set the prompt
        text to.

Return Value:

    None.

--*/

VOID
UiDisplayProfilerData (
    PROFILER_DATA_TYPE DataType,
    PROFILER_DISPLAY_REQUEST DisplayRequest,
    ULONG Threshold
    );

/*++

Routine Description:

    This routine displays the profiler data collected by the core debugging
    infrastructure.

Arguments:

    DataType - Supplies the type of profiler data that is to be displayed.

    DisplayRequest - Supplies a value requesting a display action, which can
        either be to display data once, continually, or to stop continually
        displaying data.

    Threshold - Supplies the minimum percentage a stack entry hit must be in
        order to be displayed.

Return Value:

    None.

--*/

HANDLE
CreateDebuggerLock (
    VOID
    );

/*++

Routine Description:

    This routine creates a debugger lock.

Arguments:

    None.

Return Value:

    Returns a handle to a debugger lock on success, or NULL on failure.

--*/

VOID
AcquireDebuggerLock (
    HANDLE Lock
    );

/*++

Routine Description:

    This routine acquires a debugger lock. This routine does not return until
    the lock is required.

Arguments:

    Lock - Supplies a handle to the lock that is to be acquired.

Return Value:

    None.

--*/

VOID
ReleaseDebuggerLock (
    HANDLE Lock
    );

/*++

Routine Description:

    This routine releases a debugger lock.

Arguments:

    Lock - Supplies a handle to the lock that is to be released.

Return Value:

    None.

--*/

VOID
DestroyDebuggerLock (
    HANDLE Lock
    );

/*++

Routine Description:

    This routine destroys a debugger lock.

Arguments:

    Lock - Supplies a handle to the lock that is to be destroyed.

Return Value:

    None.

--*/