Theseus HOWTOs 2012-01-24 SHL Baseline 2012-06-11 SHL Add shared memory analysis 2012-06-11 SHL Add REXX/DLL API notes 2012-06-13 SHL Add REXX leak detect API notes 2012-10-07 SHL Comments 2013-06-04 SHL Comments 2014-01-09 SHL Add Memory leak detection 2020-06-04 SHL Doc command line == Introduction == Theseus is a tool for examining memory and kernel data structures on a running system. Like many OS/2 applications, it has a REXX interface. == Command Line == ?,-?,-h,-H,-help,-HELP Show this message. -d,-D Enable debug tracing. -l,-L fn Provide file with replacement list of system .DLLs. fn = is the full-name of the file. -q,-Q Do not display the logo or the warning message for RAM Used By Process function. -a -A FIXME? -- Internals -- -d PARAMFLAGS 1 fDebug 0x80 -a PARAMFLAGS 1 PARAMFLAGS 2 maybe unused -q PARAMFLAGS 1 PARAMFLAGS 4 PARAMFLAGS 8 -l PARAMFLAGS 1 System DLL list read ==================================== == How to install and run Theseus == ==================================== - Download and install image from http://www.os2site.com/sw/util/memory/thes4001.exe or ftp://service.boulder.ibm.com/ps/products/os2/fixes/v4.5warp/theseus4/thes4001.exe This version should run on any system runing an IBM 4.5 kernel. This include eComstation and IBM MCP. Older versions of Warp require a different Theseus version. - The install image is self-extracting zip file. - Unzip the install image to a directory of your choice. - If you want to run Theseus from the Desktop, create Desktop objects for theseus.exe and theseus.inf. - If you want to run Theseus from the command line, make sure that the Theseus directory is added to PATH, LIBPATH, and DPATH or move the Theseus files to directories where they can be found via the normal PATH, LIBPATH, DPATH searches. - To start Theseus, enter theseus on the command line or double-click the Desktop object depending on how you chose to do the install. =========================== == Memory Leak Detection == =========================== Use this HOWTO to analyze one or processes for possible memory leaks. - Start Theseus if needed - From the Process Heirarchy window select the process to be analyzed. - From the Process Heirarchy window menu do Process -> Memory Leak Detection to display the Memory Leak Detection window - The Leak Detection feature defaults to a 30 second update rate. If you need a faster or slower update rates, use Misc -> Contents Update -> Options to open the Periodic Update Options dialog and adjust the settings. - To capture a set of Leak Reference Data, use Functions->Capture Leak Reference Data Generally, you want to capture the Reference Data after the process has been started and before triggering the actively that leaks memory. - The Leak Detection featue defaults to reporting the utilization changes relative to Reference Data. Sometimes, it is better to report comparing to the last sample. The do this, use Function -> Leak Detection Control to open the Leak Detection Control Dialog and check the use previous sample as base box. - To start the Leak Detection process, use Functions -> Start Periodic Leak Detection - To monitor multiple processes repeat the above for each process. There is no one best way to use the Leak Detection feature. One often needs to experiment with differ settings to find a set that expose the leak pattern. ==================================== == Private/Shared Memory Analysis == ==================================== Use this howto to determine which processes are using the most address space. - Start Theseus if needed - From the Process Heirarchy window menu do System -> General System -> Linear usage by process to display the Linear Memory Map window - From the Linear Memory Map window menu do Mark/Find -> Find and Mark/Find -> Again and search the window for the word arena - Write down the start address and size of each of the 4 arenas. - If the window does not include sizes for all 4 arenas, the window overflow notification "Theseus2's window buffer is full." will display near the bottom of the window - If this occurs, temporarily shut down some processes and try again or run the linear_memory_map.cmd REXX script from the command line, if you have it. - From the Linear Memory Map window menu do Output -> Save as and save the Linear Memory Map window to a file. - Determine which process(es) are to be analyzed individually. - Switch back to the Process Hierarchy window. - For each process, select the process instance in the Process Hierarchy window. - From the Process Heirarchy window menu do Process -> Memory Utilization to display the Memory Utilization window. - From the Memory Utilization window menu do Output -> Save as and save the Memory Utilization window to a file. - From the Process Heirarchy window menu do Process -> Private Object Summary to display the Private Object Summary window. - From the Private Object Summary window menu do Output -> Save as and save the Private Object Summary window to a file. - From the Process Heirarchy window menu do Process -> Shared Object Summary to display the Shared Object Summary window. - From the Shared Object Summary window menu do Output -> Save as and save the Shared Object Summary window to a file. - Review the saved files for unexpected/non-optimal shared memory usage. If you need assistance, ask developer that understands eCS/OS2 memory usage. =============================================================== == How to look up MTE or object table for a 32-bit LX module == =============================================================== Use this HOWTO if you need to analyze the Module Table Entry (MTE) or the object tables of a process. - Start Theseus if needed. - From the main menu, use System -> General system -> Modules to display the module list. - From the window menu, use Mark/Find -> Find and Mark/Find -> Again to locate module name in the list. - Double click on the address in MTE @ column to display the MTE. The object table is at bottom of the window. - From the window menu, use Output -> Save as to write window contents to a file. ====================================== == How to describe a linear address == ====================================== Use this HOW if you need to know how a chunk of address space was allocated or what it contains. - Start Theseus if needed. - If the address is related to a specific process, double click on the process in the process hierarchy window otherwise double click on the Sysinit process. - From the General Information window menu, use Functions -> Show description to display the Describe on object dialog. - Enter the linear address, select the LINEAR address radio button and click Enter. - From the Description window menu, use Output -> Save as to write window contents to a file. ================================================================ == How to disassemble 32-bit instructions at a linear address == ================================================================ - Start Theseus if needed. - If the address is related to a specific process, double click on the process in the process hierarchy window otherwise double click on the Sysinit process. - From the General Information window menu, use Functions -> Show memory at Linear address to display the Display memory dialog. - Enter the linear address, select the Show memory as disassembled instructions radio button, check the Code is 32-bit checkbox and click Enter. - From the Description window menu, use Output -> Save as to write window contents to a file. ==================== == REXX Interface == ==================== - Somewhat documented - Search .inf for REXX - Search .inf .hlp for RT2* with IBM view.exe - Spread across two dlls - See *.cmd - See getws.exe RT2AnalyzeSwapper RT2DumpWorkSet RT2FindProcesses RT2FreeMemory RT2GetGDTRegs RT2GetGDTTable RT2GetLinMemMap RT2GetObjSummary RT2LeakStart RT2LeakStop RT2LeakTick RT2LoadFuncs RT2LoadFuncs1 RT2RamUseByProcess RT2WSProcessTick RT2WSProcessTick2 RT2WSStart! RT2WSStop RT2WSStop2 RT2WSSystemTick RT2WorkSetDetailByObject =================== == API Interface == =================== - Somewhat documented - Search inf for T2* with IBM view.exe - See getram.exe - See theseus.h T2AnalyzeSwapper T2Debug T2FindProcesses T2FreeMemory T2GetHandle0 T2Initialize0 T2RamUseByProcess T2ReleaseHandle0 T2SetDebugVector T2SetWriteVector T2Terminate0 T2WSCheck T2WSProcessTick T2WSProcessTick2 T2WSStart T2WSStop T2WSStop2 T2WSSystemTick T2Write0 error_handler0 READ_LINEAR READ_LINEAR_ANYWAY =============================== == theseus0.dll entry points == =============================== 00001 RT2LoadFuncs 00002 T2GetHandle0 00003 T2Terminate0 00004 RT2GetGDTRegs 00005 RT2FreeMemory 00006 T2FreeMemory 00007 READ_LINEAR 00008 T2Initialize0 00009 T2WSSystemTick 00010 RT2FindProcesses 00011 T2ReleaseHandle0 00012 RT2WSSystemTick 00013 T2FindProcesses 00014 RT2WSProcessTick 00015 RT2WSProcessTick2 00016 T2WSProcessTick 00017 RT2AnalyzeSwapper 00018 T2AnalyzeSwapper 00019 T2SetDebugVector 00020 T2WSProcessTick2 00021 T2SetWriteVector 00022 T2RamUseByProcess 00023 RT2RamUseByProcess 00024 T2Debug0 00025 T2Write0 00026 READ_LINEAR_ANYWAY 00027 RT2WSStop 00028 T2WSStop 00029 T2WSCheck 00030 T2WSStop2 00031 T2WSStart 00032 RT2WSStop2 00033 RT2WSStart =============================== == theseus1.dll entry points == =============================== 00001 RT2LeakTick 00002 RT2LeakStop 00003 RT2LoadFuncs1 00004 RT2LeakStart 00005 RT2GetGDTTable 00006 RT2WorkSetDetailByObject 00007 RT2DumpWorkSet 00008 RT2GetLinMemMap 00009 RT2GetObjSummary ==================== == REXX Functions == ==================== call RxFuncAdd 'RT2LoadFuncs', 'THESEUS0', 'RT2LoadFuncs' rc = RT2LoadFuncs() call RxFuncAdd 'RT2LoadFuncs1', 'THESEUS1', 'RT2LoadFuncs1' rc = RT2LoadFuncs1() -- Processes -- call RT2FindProcesses "processList" stem contains pid ppid cThreads processName -- Object Summary -- - See getobj.cmd rc = RT2GetObjSummary(Pid , Object_type) Pid hex process id? Object_type 0 = system, 1 = shared, 2 = private rc = 0 if OK else error writes output to stdout -- Linear Memory Map -- call RT2GetLinMemMap writes output to stdout -- Leak Detection -- - See leakdet.cmd rc = RT2LeakStart('leak_handle') rc = RT2LeakStart('leak_handle', ProcessPid) rc = RT2LeakTick('leak_handle', newbase) newbase = 0 capture new base data newbase = 1 use existing base data writes output to stdout -- Working Set -- - See Theseus.inf -- EOF --