OS/2 Shareware BBS: 16 Announce

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 16 Announce / 16-Announce.zip / PTRACE.ZIP / PTRACE.DOC

Wrap

Text File | 1988-12-14 | 42KB | 1,013 lines

------------------------------------------------- What follows is a fairly complete, but informal explanation of the OS/2 DosPtrace function. This is to be used as a guide to DosPtrace, but is not to be regarded as 'official' documentation. ------------------------------------------------- The code that most applications programmers write for OS/2 consists of - Batch Files (foo.BAT and foo.CMD) - Programs (Processes and Threads) - Libraries (DLLs) - Ring 0 Device Drivers Ptrace is not intended for use with Batch Files or any object at ring 0, nor is it intended for assisting real-mode development. PTrace provides connections on a per-process basis. These connections are independent of screen groups, so that even a detached or synchronous process may be debugged. A debugger may not debug itself, nor any process that is debugging it, but a debugger may debug a copy of itself. A debugger may debug more than one process simultaneously, but any debuggee must have at most one debugger. In general, this set of debugging connections forms a collection of trees. Threads within processes are the main objects that PTrace works with. DLLs do not have threads associated with them directly, but are accessed and manipulated by threads of processes. So, PTrace supports debugging of DLLs by permitting the debugger to observe the memory of the DLL, and the registers of a thread while using the DLL. PTrace also assists the debugger in debugging DLLs by telling the debugger when a library is loaded. It also uses PTrace to get the name of a library, or to convert a logical segment number and MTE to a selector. By storing these items, debuggers can transform an address or value to a symbolic reference. * Debugging Intrusion and Limitations A debugger should be accurate, showing as closely as possible the operations that a thread or process executes. However, there are always limitations that complicate the situation. For instance, if a debugger is in use, the timing of scheduling and semaphores is affected. Note that intrusion may become a very serious matter. The most serious known problem comes when a debuggee requests and sets a semaphore, then hits a breakpoint. If the debugger requests this same semaphore, without letting the debuggee clear it, a deadlock will occur. This can happen with any semaphore, including semaphores not implemented by the OS/2 base. This becomes most serious when it happens to a semaphore vital to the operation of the system, such as the VIO semaphore. * Ptrace Errors If (AX) is nonzero, the Ptrace buffer is invalid. This was caused by an error that prevented the Ptrace command from being executed at all, such as a GP fault while reading the buffer. If Ptrace returns (AX) = ERROR_INTERRUPT after a command, the next notification may have been lost. If the debuggee was executing code at that time, (via a Go or SStep command) it will be automatically stopped. To prevent this, it is recommended that DosPtrace not be used by thread 1 when signals are being used. * Ptrace Buffer Format The Ptrace buffer (as defined in the manuals) contains : - Pid - Debuggee's Process ID - Tid - Debuggee Thread ID - Cmd - PTrace Command or Notification number. - Value - Generic data. - Seg,Off - Generic far pointer. - Mte - Debuggee's program module MTE handle. (Usually) - Application Register Set * Command Numbers 0 TRC_C_Null ; Null 1 TRC_C_ReadMem ; Read Word 1 TRC_C_ReadMem_I ; Read Word (instruction) 2 TRC_C_ReadMem_D ; Read Word (data) 3 TRC_C_ReadReg ; Read Registers 4 TRC_C_WriteMem ; Write Word 4 TRC_C_WriteMem_I ; Write Word (instruction) 5 TRC_C_WriteMem_D ; Write Word (data) 6 TRC_C_WriteReg ; Write Registers 7 TRC_C_Go ; Go 8 TRC_C_Term ; Terminate 9 TRC_C_SStep ; Single Step 10 TRC_C_Stop ; Stop 11 TRC_C_Freeze ; Freeze Thread 12 TRC_C_Resume ; Resume Thread 13 TRC_C_NumtoSel ; Segment Number to Selector 14 TRC_C_GetFPRegs ; Get 80287 Registers 15 TRC_C_SetFPRegs ; Set 80287 Registers 16 TRC_C_GetLibName ; Get Library Name 17 TRC_C_ThrdStat ; Thread Status 18 TRC_C_MapROAlias ; Map Read-Only Memory Alias 19 TRC_C_MapRWAlias ; Map Read-Write Memory Alias 20 TRC_C_UnMapAlias ; UnMap Memory Alias * Notification Numbers 0 TRC_C_SUC_ret ; Success -1 TRC_C_ERR_ret ; Error -2 TRC_C_SIG_ret ; Signal -3 TRC_C_TBT_ret ; Single-Step -4 TRC_C_BPT_ret ; Breakpoint -5 TRC_C_NMI_ret ; NMI (NOT USED) -6 TRC_C_KIL_ret ; Process Termination -7 TRC_C_GPF_ret ; GP Fault -8 TRC_C_LIB_ret ; DLL Library Attachment -9 TRC_C_FPE_ret ; Floating Point Error -10 TRC_C_THD_ret ; Thread Termination -11 TRC_C_STP_ret ; Asynchronous Stop -12 TRC_C_NEW_ret ; New Process -13 TRC_C_AFR_ret ; Alias Free * Error numbers with TRC_C_ERR_ret : 1 trace_bad_command ; command failed 2 trace_child_not_found ; process not found 5 trace_child_untraceable ; cannot debug this process * Command Parameters Not all fields need to be defined on every Ptrace command, and the meanings of some fields change on a per-command basis. This is a list of the parameters for each command and notification. PTB fields not listed are not useful for that command. Error cases for each command are not listed here. Null Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_Null -- Returns No operation is performed on the debuggee. Pid must be valid, or an error will be returned. -- Unchanged All except Seg, Off Read Registers Command -- Parameters Pid = Process ID of debuggee TID = Thread ID of register set to read. If 0, the register set comes from the 'current' thread of the debuggee. Cmd = TRC_C_ReadReg -- Returns The register set is updated. The register set includes all general, segment, and control registers. TID = Thread ID corresponding to register set. MTE = Program module's MTE handle -- Unchanged Pid, Seg, Off Write Registers Command -- Parameters Pid = Process ID of debuggee TID = Thread ID of register set to write. If 0, the register set goes to the 'current' thread of the debuggee. Cmd = TRC_C_WriteReg All general, segment, and control registers contain desired values. Reserved system or processor flags can not be modified via this method, but are silently masked to their correct values. -- Returns TID = Thread ID corresponding to register set. -- Unchanged Pid, MTE, Seg, Off, Register set. Read Word Command -- Parameters Pid = Process ID of debuggee Seg:Off = Address to read from Cmd = TRC_C_ReadMem_I Cmd = TRC_C_ReadMem_D Cmd = TRC_C_ReadMem (These 3 commands are identical) -- Returns The word at the desired address is read, and stored into Value. Value = word read from the desired location -- Restrictions Unable to read from one-byte segments Unable to read from execute-only segments Unable to read from ring 0 OK to read from both InfoSeg segments, and GDT segments Write Word Command -- Parameters Pid = Process ID of debuggee Seg:Off = Address to write to Value = word to write Cmd = TRC_C_WriteMem_I Cmd = TRC_C_WriteMem_D Cmd = TRC_C_WriteMem (These 3 commands are identical) -- Returns The word in Value is written to the address specified by Seg:Off. In the case of a write to a shared code segment, the segment is converted to a private segment, and any set Dynamic RAS tracepoints are removed from that segment before the write is performed. DynamicTrace will continue to function in that segment, in the context of other processes. The segment will continue to be shared by those other processes, if any exist. Breakpoints may be set in the debuggee without affecting the other modules. -- Restrictions Unable to write to one-byte segments Unable to write to ring 0 Unable to write to GDT segments Unable to write to LDT InfoSeg Unable to write to execute-only segments Stop Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_Stop -- Returns * If debuggee is stopped If there is a pending notification from the current thread, it is returned. Otherwise, Success is returned. * If the debuggee is running user code The debuggee is marked to stop before the next time it is ready to run user-space (ring 2 or 3) code. Kernel operations will not be interrupted for this Asynchronous stop command. That is, threads blocked in the kernel (via a semaphore or internal operation) will not be interrupted, but an infinite loop in user space will. The PTB register set may be inaccurate when the Stop command finishes. If the debuggee thread was stopped via an AsyncStop command, an AsyncStop notification will be returned to the debugger thread which issued the Go command, with an accurate register set. Note that the AsyncStop command implies a debugger with a minimum of 2 threads - one waiting for a Go command to finish, and one doing the Stop command. Go Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_Go -- Returns All non-frozen threads of the debuggee are allowed to run user code at once. If all of the debuggee threads are frozen, an error is returned. The Go command completes when a Ptrace event (such as a breakpoint) occurs. This can be any one of the notifications listed below. When the next Ptrace event occurs, all threads in the debuggee are marked to not run any additional user code until the next Go command is issued. This provides a stable environment for debugging. When the Go command returns, the TID, MTE, and register set are automatically updated to reflect the thread which detected the event. The thread which detected the event becomes the 'current' thread, used to determine which thread to access if TID=0, on some of the commands. This 'current thread' method is not recommended. By simply not modifying the TID field of the PTB, the same affect can be generated. Single Step Command -- Parameters Pid = Process ID of debuggee Tid = Thread ID of thread to single-step. If 0, all threads will be marked to single-step, and the first thread to be scheduled to run user-space code will single-step. Cmd = TRC_C_SStep -- Returns Most likely, the SStep notification will be returned, but any notification may be returned. See the section on notifications. Callgates that result in a privilege level transition to ring 0 will appear to single-step as a single instruction, with the single-step occurring just after the function completes. If Tid is nonzero, the thread will single-step even if it was marked frozen. However, if Tid is zero, the frozen threads will not single-step. -- Restrictions Callgate single-stepping must be simulated because the flags (specifically, the TF bit) are not stored in the ring 0 callgate stack frame. Because of this, a single-step which results in leaving a ring 0 callgate will sometimes not execute any user-space code. The next single-step should function normally, however. Terminate Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_Term -- Returns The debuggee process is terminated immediately. No additional Ptrace commands or notifications will be allowed to this process. Memory aliases to the debuggee will be invalidated automatically. Debuggee ExitList processing will be attempted, but any Ptrace event (such as a breakpoint) during this period will cause the process to terminate without completing the ExitList processing. If the Terminate command is issued during ExitList processing, ExitList processing will terminate immediately, without continuing the ExitList routine. Freeze Thread Command -- Parameters Pid = Process ID of debuggee Tid = Thread ID of thread to freeze. If 0, all debuggee threads will be frozen. Cmd = TRC_C_Freeze -- Returns The desired thread(s) are prevented from running user code on a Go or SStep command. Note that this can be defeated when single-stepping a specific thread. By using the Freeze and Resume commands, a given set of threads can be run at once, while keeping the other threads suspended. No error is returned if the thread was previously frozen - it just remains frozen. Freeze and Resume commands do not nest. A single Resume command will thaw a thread frozen multiple times. If the TID was zero, it will be set to the TID of the 'current' thread. Resume Thread Command -- Parameters Pid = Process ID of debuggee Tid = Thread ID of thread to thaw. If 0, all debuggee threads will be thawed. Cmd = TRC_C_Resume -- Returns The resume command complements the freeze command. A thread which has been resumed will function as if it was never frozen. No error will be returned if the thread was not previously frozen If the TID was zero, it will be set to the TID of the 'current' thread. Get 80287 Registers Command -- Parameters Pid = Process ID of debuggee TID = Thread ID of NPX register set to read. If 0, the register set comes from the 'current' thread of the debuggee. Cmd = TRC_C_GetFPRegs Seg:Off -> 287 NPX context buffer. This NPX context buffer format is the same as that defined by the fsave/frestore instructions as executed by the 80287 chip. -- Returns Debugger's 287 NPX context buffer filled in with registers read from the NPX chip, for the Thread specified in the Tid field. If the TID was zero, it will be set to the TID of the 'current' thread. -- Restrictions An error will be returned if the debuggee process is emulating the NPX, or if the desired debuggee thread has not yet attempted to use the NPX. Set 80287 Registers Command -- Parameters Pid = Process ID of debuggee TID = Thread ID of NPX register set to write. If 0, the register set goes to the 'current' thread of the debuggee. Cmd = TRC_C_SetFPRegs Seg:Off -> Debugger's 287 NPX context buffer. This NPX context buffer format is the same as that defined by the fsave/frestore instructions as executed by the 80287 chip. -- Returns 287 NPX registers filled in from passed-in buffer, to the Thread specified in the Tid field. If the TID was zero, it will be set to the TID of the 'current' thread. -- Restrictions An error will be returned if the debuggee process is emulating the NPX, or if the desired debuggee thread has not yet attempted to use the NPX. The 287 NPX processor may adjust some control register bits, but Ptrace will not return an error if a modification is attempted. Because of internal NPX management, this adjustment may be delayed until the thread actually uses the NPX again. Convert Segment Number to Selector Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_NumtoSel Value = Logical segment number MTE = MTE handle of module of interest -- Returns Value is converted into a selector (valid in the debuggee's memory space) that maps the requested logical segment of the requested module. The logical segment numbers are generated at link time. By using this function, selectors can be mapped back to logical segment numbers. Once the logical segment number is known, symbols can be generated via a map or symbol file, for symbolic debugging. Get Library Name Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_GetLibName Value = MTE handle of module of interest Seg:Off = Pointer to Debugger's LibName buffer. The debugger should reserve enough memory space at the desired location to hold a fully qualified path name. -- Returns The fully qualified path name of the module corresponding to the MTE handle in Value is returned to the debugger at the location pointed to by Seg:Off. The GetLibName command is useful for generating a path to a symbol file to aid in symbolic debugging. Thread Status Command -- Parameters Pid = Process ID of debuggee TID = Thread ID of thread of interest. If 0, the status of the 'current' thread will be returned. Cmd = TRC_C_ThrdStat Seg:Off = pointer to Thread Status buffer Thread Status buffer format TStat struc DbgState db ? TState db ? TPriority dw ? TStat ends -- Returns Value = Thread ID of 'next' active thread Tid = Thread ID matching status The thread status buffer will be filled in with the following values, depending on the thread's state. The DbgState byte gives information about the state of debugging, while the TState byte gives information about scheduling. TStat.DbgState values : TRC_C_Thawed equ 0 TRC_C_Frozen equ 1 TStat.TState values : TRC_C_Runnable equ 0 TRC_C_Suspended equ 1 TRC_C_Blocked equ 2 TRC_C_CritSec equ 3 TStat.TPriority will be the thread's scheduling priority. The Value field will be filled in with the Thread ID of the 'next' thread to look at. By repeatedly calling the ThrdStat command, replacing the Tid with the last returned Value, until a thread ID is repeated, all threads in the process can be traversed. The TIDs returned by the ThrdStat command form a loop. Map Read-Only Memory Alias Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_MapROAlias Value = Debugger alias selector to be remapped. If 0, a new alias will be mapped. Seg = Debuggee selector to alias to. -- Returns Value = Debugger alias selector Off = Segment limit of alias selector A read-only alias to the debuggee's selector is mapped into the debugger's memory space. This selector is reserved for use as an alias until it is unmapped. Because the segment cannot be written to via a read-only segment, DynamicTrace tracepoints are left in shared code, and the segment is not made private. For this reason, Read-only aliases should be used when simply perusing code, to conserve system resources. Only selectors returned by a previous Ptrace call to map an alias may be remapped. It is okay to remap a read-write alias from a read-only alias, and vice versa, but a selector returned via other memory management calls (such as AllocSeg) may not be used. Most other memory management calls may not be used on these aliases. When the debuggee frees the segment, an alias-free notification is returned to the debugger. See the notification section for details. If the debuggee changes the size of the segment, the size of the alias will be updated to match, without telling the debugger. For this reason, it is recommended that debuggers access this alias segment only when the debuggee is not running, and after checking the size of the segment, to prevent the debugger from faulting. This command may be performed while the debuggee is executing code via a Go command. The alias may be accessed while the debuggee is running. Map Read-Write Memory Alias Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_MapRWAlias Value = Debugger alias selector to be remapped. If 0, a new alias will be mapped. Seg = Debuggee selector to alias to. -- Returns Value = Debugger alias selector Off = Segment limit of alias selector A read-write alias to the debuggee's selector is mapped into the debugger's memory space. This selector is reserved for use as an alias until it is unmapped. Because the segment can be written to, if it is a shared code segment, DynamicTrace tracepoints are removed, and the segment is made private. Only selectors returned by a previous Ptrace call to map an alias may be remapped. It is okay to remap a read-write alias from a read-only alias, and vice versa, but a selector returned via other memory management calls (such as AllocSeg) may not be used. Most other memory management calls may not be used on these aliases. When the debuggee frees the segment, an alias-free notification is returned to the debugger. See the notification section for details. If the debuggee changes the size of the segment, the size of the alias will be updated to match, without telling the debugger. For this reason, it is recommended that debuggers access this alias segment only when the debuggee is not running, and after checking the size of the segment, to prevent the debugger from faulting. This command may be performed while the debuggee is executing code via a Go command. The alias may be accessed while the debuggee is running. -- Restrictions A number of segments, such as the infoseg, GDT segments, and the like, cannot be mapped to. UnMap Memory Alias Command -- Parameters Pid = Process ID of debuggee Cmd = TRC_C_UnMapAlias Value = Debugger alias selector to be unmapped. -- Returns The UnMapAlias command is used when the debugger has finished using an alias selector, and wishes to return it to the selector pool. Both read-only and read-write aliases may be freed in this way. A selector returned from other memory management calls (such as AllocSeg) may not be used. This command may be performed while the debuggee is executing code via a Go command. When the debuggee process finally terminates, all aliases to it's memory space will be invalidated. -- Restrictions A number of segments, such as the infoseg, GDT segments, and the like, cannot be mapped to. * Notification Parameters Success Notification -- Meaning The Ptrace command was successful. -- Returns Cmd = TRC_C_SUC_ret Other returned values depend on which command was executed - see Commands section. Error Notification -- Meaning An error was detected while attempting a Ptrace command. -- Returns Cmd = TRC_C_ERR_ret Value = * trace_bad_command - The Ptrace command failed, probably because of invalid parameters. * trace_child_not_found - The process could not be located from the given Pid. * trace_child_untraceable - The process was located, but is either not marked for debugging, or is being debugged by another debugger. Signal Notification -- Meaning The debuggee process is about to set up to dispatch to a signal handler. A bit vector of pending signals is returned in the low byte of Value. If more than one signal is pending, which signal handler that gets dispatched to first is undetermined. -- Returns Cmd = TRC_C_SIG_ret Value = Bit vector of pending signals Seg:Off = 0:0 The bit positions in the low byte of Value correspond to signal numbers. Bit Name Meaning 0 ------- reserved 1 SIGINTR Ctrl-C 2 ------- reserved 3 SIGTERM Program termination 4 SIGBREAK Ctrl-Break 5 SIGPFA Process flag A 6 SIGPFB Process flag B 7 SIGPFC Process flag C Single-Step Notification -- Meaning A single-step trap has been detected. This occurs when an instruction is executed with the TF bit set. This can be done via the SStep command. -- Returns Cmd = TRC_C_TBT_ret Value = 0 Seg:Off = CS:IP location of SStep Breakpoint Notification -- Meaning A breakpoint trap has been detected. This occurs when the int 3 software interrupt is executed. The debuggee's IP location is automatically decremented by 1 to adjust for the length of the one-byte int 3 instruction. The two-byte form is not recommended for this reason. -- Returns Cmd = TRC_C_BPT_ret Value = 0 Seg:Off = user's CS:IP (decremented by 1) NMI Notification (NOT USED) -- Meaning A nonmaskable interrupt has been detected. This is meaningless in protected mode, and is never returned. Process Termination Notification -- Meaning The debuggee process is about to terminate. All ExitList processing is complete at this point. The debugger is still allowed to examine the debuggee's final register and memory contents at this time. Note that when the debugger has completed this post-mortem examination, it should finish terminating the debuggee process with a final Go, SStep, or Terminate command. Value contains the return code from the process. This return code is the same as that returned via a DosCWait call. -- Returns Cmd = TRC_C_KIL_ret Value = Process return code (CWait Exit_Code) Seg:Off = 0:0 GP Fault Notification -- Meaning A General Protection fault has been detected. The debugger is allowed to fix the faulting condition and restart the operation. The debuggee is not automatically terminated. The error code from the fault, as passed by the hardware, is returned via the Value field. This is either zero, or a selector. Note that the RPL bits of the selector are always cleared by the processor. -- Returns Cmd = TRC_C_GPF_ret Value = Exception error code from processor Seg:Off = CS:IP location or SStep -- Restrictions The (CX) register may not be valid after a GP fault because of a hardware problem with some 80286 processors. DLL Library Load Notification -- Meaning A DLL library has just been attached to the module. This occurs either at program startup, or during a DosLoadModule call. The module's handle is returned via Value, for use in the GetLibName and NumToSel commands, for symbolic debugging. There may be many module attachments done at one time, but Ptrace is only able to communicate a single load during any one notification. In this case, the additional library load notifications become pending. The debugger should do repeated Stop commands to be notified of these additional library loads, until Success is returned from the Stop command. If the Go or SStep commands are used instead of the Stop command, the pending notifications will be returned immediately, until there are no further notifications. -- Returns Cmd = TRC_C_LIB_ret Value = MTE handle of newly attached library Seg:Off = 0:0 Floating Point Error Notification -- Meaning An error was detected while processing the GetFPRegs or SetFPRegs commands. This can happen because the debuggee is emulating the NPX, or if the debuggee thread has not yet used the NPX processor. -- Returns Cmd = TRC_C_FPE_ret Value = undefined Seg:Off = unchanged Thread Termination Notification -- Meaning A debuggee thread is about to terminate. ExitList processing has not yet been started. The debugger is still allowed to examine the debuggee thread's final register contents at this time. Note that when the debugger has completed this post-mortem examination, it should finish terminating the debuggee thread with a final Go, or SStep command. Value contains the return code from the thread. Note that this is only a proposed return code, as passed in from DosExit. Only when the process actually terminates is the return code that is passed via CWait finally known. -- Returns Cmd = TRC_C_THD_ret Value = Thread's proposed return code (from DosExit) Seg:Off = 0:0 Asynchronous Stop Notification -- Meaning An Asynchronous Stop request has been detected. The asynchronous stop command is used to get the attention of some debuggee thread, so that the debugger can again control the process. Because any notification results in the debuggee coming under control of the debugger again, the asynchronous stop notification becomes redundant in that case. The asynchronous stop request will be overridden and ignored if another notification may be performed. An asynchronous stop notification never becomes a 'pending' notification, in the sense that a library attachment notification becomes pending. -- Returns Cmd = TRC_C_STP_ret Value = 0 Seg:Off = 0:0 New Process Notification -- Meaning The debuggee process has just started a child process, and that child process needs to be debugged. -- Returns Cmd = TRC_C_NEW_ret Value = Pid of the new process. Seg:Off = 0:0 Alias Free Notification -- Meaning A segment that has an alias attached to it is about to be freed by the debuggee. The alias selector must be remapped or unmapped before the debugger may run the debuggee again. The UnMapAlias command is the usual response to an alias free notification. The other proper response is to remap the alias that is being freed to another debuggee segment. Value contains the debugger alias selector that needs to be remapped or unmapped. -- Returns Cmd = TRC_C_AFR_ret Value = Alias selector that needs to be freed Seg:Off = 0:0