http://www.sgi.com/tech/relnotes/6_0rel/WorkShop.html (Silicon Surf Promotional CD, 01/1995)5 Known Problems and Workarounds
7 Licensing WorkShop with NetLS
- 1 - 1. Introduction CASEVision/WorkShop is a set of four integrated programming tools that enable the individual programmer to analyze code structure, to debug compiled code, to tune run-time performance, and to analyze code for test coverage. Together the WorkShop tools provide a multi-view, interactive programming environment for developing software in C, C++, or Fortran. The four main WorkShop components are the debugger cvd, the static analyzer cvstatic, the performance analyzer cvspeed, and the coverage analyzer, cvcov (also known as Tester). In addition, WorkShop also provides a context-sensitive on-line help system, an annotated source code viewer, a build analyzer, and online documentation. Note: Packaged with the product is a separate sheet that contains the Software License Agreement. This software is provided to you solely under the terms and conditions of the Software License Agreement. Please take a few moments to review the Agreement. This document contains the following chapters: 1. Introduction 2. Installation Information 3. Changes and Additions 4. Bug Fixes 5. Known Problems and Workarounds 6. Documentation Errors 7. Licensing WorkShop with NetLS 1.1 Release_Identification_Information Following is the release identification information for WorkShop: - 2 - Software Option Product CASEVision/WorkShop Version 2.3 Product Code SC4-WS-2.3 System Software Requirements IRIX 6.0 Note: WorkShop 2.3 runs only on IRIX 6.0 or greater. 1.2 Hardware_Requirements You should have at least 32 Mbytes of RAM to run WorkShop. Furthermore many of the programs have large address spaces and therefore use a large amount of swap space. Silicon Graphics suggests that if you see the tools being killed due to lack of swap space, increase the virtual swap with chkconfig vswap. 1.3 License_Requirements You must have a license to run WorkShop. There are two types of licenses applicable to WorkShop: node-locked and concurrent access. Node-locked licenses are valid only on the machines where they are installed. Concurrent access licenses can be passed around to different machines on the network. WorkShop's initial temporary license is node- locked, and the permanent license can be either node-locked or concurrent access. See Chapter 7, ``Licensing WorkShop with NetLS'' for more details about obtaining and installing your license. You cannot run the product until you have a license installed. 1.4 On-Line_Release_Notes After you install the on-line release notes for a product (the relnotes subsystem), you can view the release notes on your screen. Note: You can read the online release notes for most products before installing the software. Refer to the booklet in your CD-ROM case for more information. If you have a graphics system, select ``Release Notes'' from the Tools submenu of the Toolchest. This displays the grelnotes(1) graphical browser for the on-line release notes. - 3 - Refer to the grelnotes(1) man page for information on options to this command. If you do not have a graphics system, you can use the relnotes command. Refer to the relnotes(1) man page for accessing the on-line release notes. 1.5 On-line_Man_Pages The following man pages are provided on-line with WorkShop: cvd(1) cvexprnt(1) cvhang(1) cvinstr(1) cvmeter(1) cv_gl_controller(1) cvspeed(1) cvstatic(1) cvmake(1) cvusage(1) cvxhang(1) cvbuild(1) cvperf(1) cvconfig(1) cvcov(1) cvxcov(1) malloc_cv(3) To access an on-line man page, type: man1.6 On-line_Documentation WorkShop 2.3 includes on-line versions of the WorkShop User's Guide and the CASEVision Environment Guide. After installing the WorkShop.books and CaseVision.books subsystems, you can view the books with insight(1). 1.7 Product_Support Silicon Graphics, Inc., provides a comprehensive product support and maintenance program for its products. If you would like support for your Silicon Graphics-supported products, contact the Technical Assistance Center at 1-800- 800-4SGI. If you are outside of North America, contact the Silicon Graphics subsidiary or authorized distributor in your country. - 1 - 2. Installation_Information This chapter lists supplemental information to the IRIS Software Installation Guide. The information listed here is product-specific; use it with the Installation Guide to install this product. 2.1 CaseVision_and_WorkShop_Subsystems The CaseVision product is required for installing WorkShop; it includes these subsystems: CaseVision.books.CASE_EG CaseVision Online Books CaseVision.man.helpcards CaseVision Online Help Cards CaseVision.sw.cvproj CaseVision Project view CaseVision.sw.cvsource CaseVision Source Editor CaseVision.sw.help CaseVision Online Help Executables CaseVision.sw.launch CaseVision System Launch CaseVision.sw.links CaseVision Links and Base Software CaseVision.sw.pcsd CaseVision Daemon CaseVision.sw.schemes CaseVision Scheme Files CaseVision.sw.ttutil CaseVision ToolTalk Utility The WorkShop product includes these subsystems: WorkShop.books.WRKSHP_UG WorkShop User's Guide WorkShop.man.online WorkShop Online Help Cards WorkShop.man.pages WorkShop Manual Pages WorkShop.man.relnotes WorkShop Release Notes WorkShop.sw.compiler WorkShop/Delta Compiler Front-end WorkShop.sw.cvbuild WorkShop Build Browser WorkShop.sw.cvcov WorkShop Tester - 2 - WorkShop.sw.cvd WorkShop Debugger WorkShop.sw.cvspeed WorkShop Performance Analyzer WorkShop.sw.cvstatic WorkShop Static Analyzer WorkShop.sw.demos WorkShop Demo Programs WorkShop.sw.environment WorkShop Base Environment WorkShop.sw.lib64 WorkShop 64 Bit Library WorkShop.sw.links WorkShop Links 2.2 CaseVision and WorkShop Subsystem Disk Space Requirements This section lists the subsystems (and their sizes) of the CaseVision and WorkShop options. If you are installing this option for the first time, the subsystems marked ``default'' are the ones that are installed if you use the ``go'' menu item. To install a different set of subsystems, use the ``install,'' ``remove,'' ``keep,'' and ``step'' commands in inst to customize the list of subsystems to be installed, then select the ``go'' menu item. Note: The listed subsystem sizes are approximate. Refer to the IRIS Software Installation Guide for information on finding exact sizes. Subsystem Name Subsystem Size (512-byte blocks) CaseVision.books.CASE_EG 4741 CaseVision.man.online 581 (default) CaseVision.sw.cvproj 769 (default) CaseVision.sw.cvsource 1717 (default) CaseVision.sw.help 3754 (default) CaseVision.sw.launch 29 (default) - 3 - CaseVision.sw.links 105 (default) CaseVision.sw.pcsd 45 (default) CaseVision.sw.schemes 99 (default) CaseVision.sw.ttutil 135 (default) WorkShop.books.WRKSHP_UG 44495 - 4 - WorkShop.man.online 2597 (default) WorkShop.man.pages 141 (default) WorkShop.man.relnotes 161 (default) WorkShop.sw.compiler 6058 (default) WorkShop.sw.cvbuild 4836 (default) WorkShop.sw.cvcov 6143 (default) WorkShop.sw.cvd 44717 (default) WorkShop.sw.cvspeed 8651 (default) WorkShop.sw.cvstatic 5296 (default) WorkShop.sw.demos 1609 (default) WorkShop.sw.environment 1416 (default) WorkShop.sw.lib64 1723 (default) WorkShop.sw.links 130 (default) 2.3 Installation_Method All of the subsystems for CaseVision and WorkShop can be installed using IRIX. You do not need to use the miniroot. Refer to the IRIS Software Installation Guide for complete installation instructions. 2.4 Prerequisites You must be running release IRIX 6.0 to use Release 2.3 of this product, and you must have installed the ToolTalk execution environment (tooltalk_eoe.sw), the X11 Execution environment (x_eoe.sw.eoe) and the Motif Execution environment (motif_eoe.sw.eoe). WorkShop also requires the use of an ICCCM compliant window manager, for example 4Dwm, mwm, twm. - 5 - You must have Insight installed to view the online books. WorkShop requires the installation of the CaseVision environment: CaseVision.sw.ttutil, CaseVision.sw.schemes, CaseVision.sw.links, CaseVision.sw.pcsd. Within WorkShop, WorkShop.sw.environment must be installed for WorkShop.sw.cvbuild, WorkShop.sw.cvcov, WorkShop.sw.cvd, WorkShop.sw.cvspeed, and WorkShop.sw.cvstatic. In addition, WorkShop.sw.cvd must be installed for WorkShop.sw.cvspeed, WorkShop.sw.compiler must be installed for WorkShop.sw.cvstatic, and WorkShop.sw.cvspeed must be installed for WorkShop.sw.cvcov. Note: In order to compile the jello demo (from WorkShop.sw.demos), you must have the gl_dev.sw.gldev subsystem installed. 2.5 Configuration_Files WorkShop is configured with color scheme files (located in /usr/lib/X11/schemes) installed by CaseVision.sw.schemes and app-defaults files (located in /usr/lib/X11/app-defaults). Under normal circumstances, you do not have to modify either of these sets of files. You may configure your colors by choosing one of the schemes provided in /usr/lib/X11/schemes and setting the X resource *scheme. For example, if you like deep purples, put the following line in your .Xdefaults file: *scheme: VanGogh Alternatively, if you are red-green colorblind, you might choose Gainsborough, which does not use any red-green distinctions. WorkShop Tester is configured with a default instrumentation file (located in /usr/WorkShop/usr/lib/WorkShop/Tester/default_instr_file). This is used to set up default criteria for instrumenting your program for test coverage counting and tracing. Under normal circumstances, you do not have to modify this file. 2.6 Installing_WorkShop_on_a_Different_Disk_or_on_a_Server Because WorkShop is rather large and space under /usr is usually tight, WorkShop uses an installation architecture that makes it easy to relocate the bulk of the installed files to directories that have extra space. All the - 6 - WorkShop files (except the man pages, the demos, and the books) are installed under the directory /usr/WorkShop, then those files are linked back to the appropriate spots under /usr. Therefore if you do not have enough disk space on /usr to install the tools, you can install them on an auxiliary disk and link them back to /usr automatically. Here is one example of appropriate commands for installing on a disk named /disk3 from a locally mounted CDROM drive (execute as root): - 7 - ln -s /disk3/WorkShop /usr inst -f /CDROM/dist >install all >go These commands link the /usr/WorkShop directory to the /disk3 disk, where there is enough space to hold the files. The files are then installed on /disk3 and the WorkShop.sw.links subsystems install links pointing to those files from /usr. In another example, if you want to install WorkShop on a file server and have users mount the software from there, first install the software on the server as usual: inst -f /CDROM/dist Next mount the server machine's files from server:/usr/WorkShop on the user's machine as /usr/WorkShop. Then, on the client machine, install the CaseVision image, the WorkShop links subsystems, and optionally, the demos, man pages and books subsystem: inst -f /CDROM/dist >keep WorkShop >install WorkShop.sw.links >install WorkShop.sw.demos >install WorkShop.man.pages >install WorkShop.books.WRKSHP_UG >go - 1 - 3. Changes_and_Additions This chapter lists the changes and additions that have been made since WorkShop 2.2. 3.1 New_Features_in_This_Release WorkShop now supports debugging and analyzing 64-bit executables built using either the MIPS3 or MIPS4 ABI (application binary interface) protocols (that is, programs that were built with the -mips3 or -mips4 flags) in addition to 32-bit executables. The ability to support 64-bit executables has three general consequences: o Any WorkShop view that can display addresses (pointers) can display the 64-bit addresses. o Any WorkShop view that can display registers shows the new configurations of registers and precisions available in MIPS3 and MIPS4. The details are discussed in the WorkShop Debugger changes section. o Any WorkShop view that displays disassembled source code displays the 64-bit instruction set as well as the 64-bit addresses. 3.2 Changes_in_the_Debugger o The support for 64-bit C++ debugging is rudimentary. The C subset works reasonably well but other parts of C++ support are problematic. o The Debugger lets you switch back and forth between sessions debugging 32-bit and 64-bit executables. o In Main View, the PC address displays as a 64-bit address for MIPS3 and MIPS4 executables. The PC address appears in the Status field at the top of the window and in the Debugger command line at the bottom of the window. o The Result column in Expression View displays 64-bit addresses for MIPS3 and MIPS4 executables when you select the "Address Of" menu item in the Format menu. o The Result column in Variable Browser displays 64-bit addresses for MIPS3 and MIPS4 executables when you select the "Address Of" menu item in the Format menu. - 2 - o The Address field and address column display in Memory View displays 64-bit addresses for MIPS3 and MIPS4 executables. o The source display area in Disassembly View now displays the 64-bit instruction set and the 64-bit addresses for MIPS3 and MIPS4. The address fields in the "Address..." and "Function..." dialog boxes accessed from the Disassemble menu can accommodate 64- bit addresses for MIPS3 and MIPS4 executables. o Register View has changed the most radically of any of the Debugger views. Here's a comparison of Register View running a MIPS1 executable versus a MIPS4 executable: - Register View has 32 32-bit general purpose registers for MIPS1 executables and 32 64-bit general purpose registers for MIPS4. - Register View has five 32-bit special purpose registers for MIPS1. For MIPS4 executables, there are four 64-bit special registers and one 32-bit register (fpscr). - Register View has 16 32-bit floating point registers for MIPS1 executables and 32 32-bit floating point registers for MIPS4. - Register View has 16 64-bit double-precision registers for MIPS1 executables and 32 64-bit double-precision registers for MIPS4. The printregs command on the Debugger command line will print out the register values for the MIPS1 and MIPS4 ABIs as well. o The following assignment operators for C expressions are now supported in Expression View and the Expression Evaluator dialog box: = += -= /= %= >>= <<= &= ^= |= These should be used with caution to avoid inadvertently modifying a variable while stepping through a program. - 3 - 3.3 Changes_in_the_Static_Analyzer The Static Analyzer has no new functionality in this release. You can create both parsed and scanned static analysis databases using the Fileset Editor as before. The major difference in this release is that you cannot use the f77 compiler with the -sa flag to create parsed static analysis databases for 64-bit Fortran programs. To create a parsed static analysis for 64-bit Fortran programs, you need to type from a command line: /usr/WorkShop/usr/bin/f77 -sa This invokes the special WorkShop f77 compiler, which can create a static analysis database but no compatible object code. Use the standard Fortran compiler f77 to actually compile your 64-bit programs. As in WorkShop 2.2, you can use the C and C++ compilers, ncc and NCC, with the -sa flag to create parsed static analysis databases for either 32-bit or 64-bit programs. Similarly, for 32-bit Fortran programs, you can use the f77 Fortran compiler with -sa flag to create parsed static analysis databases. You can still create parsed and scanned databases for any language through the cvstatic graphical interface. 3.4 Changes_in_the_Performance_Analyzer o The performance tools now work on both 32- and 64-bit non-shared executables with two exceptions: - You cannot perform malloc/free tracing on non- shared executables. The libexc.a library is not available. - You cannot perform fpe tracing on 64-bit programs, shared or non-shared. There is no libfpe.so shared object for 64-bits or libfpe.a library for non- shared programs. o The Performance Analyzer can now obtain performance data equivalent to pixie and pixstats. This lets you see metrics based on the time that instructions were available for processing but could not be completed for some reason, such as branch, function unit, or operand delays. - 4 - To capture pixie data, you select the task "Get Ideal Time (pixie) per function & source line" from the Task menu in the Performance Panel. (This task was formerly called "Get Ideal Time per function & source line".) The new version of the task enables you to show the following types of performance data in your experiments: - Inclusive percentage time - the percentage of time that instructions in this function (and any called functions) were available for processing but could not be processed. - Exclusive percentage time - the percentage of time that instructions in this function (excluding any calls) were available for processing but could not be processed. - Inclusive cycles - the number of elapsed cycles in this function, line of code, or instruction (including any calls). - Exclusive cycles - the number of elapsed cycles in this function, line of code, or instruction (excluding any calls). - Instruction coverage - the percentage of the instructions within each function that were actually executed. In the disassembled source, branch-taken counts are displayed. Branch-taken counts show the number of times that each conditional branch was taken. - Pixstats/Cycles-per instruction - the ratio of cycles to instructions. In a classic RISC machine, the Pixstats/Cycles-per instruction ratio would be 1.0. If the ratio is much greater than 1.0, you should check the disassembled source to determine the reasons for this inefficiency. Clicking the Disassembled Source button in the Performance Analyzer displays the disassembled code in a Source View window with a special three-part annotation. A yellow bar spanning the top of three columns in this annotation indicates the first instruction in each basic block. The first column labelled Clock in the annotation displays the clock number in which the instruction issues relative to the start of a basic block. If you see clock numbers replaced by ditto marks ("), it means that multiple instructions were issued in the same cycle. The second column is labelled - 5 - Stall and shows how many clocks elapsed during the stall before the instruction was issued. The third column labelled Why shows the reason for the stall. There are three possibilities: o B - branch delay o F - function unit delay o O - operand hasn't arrived yet o The Performance Analyzer also provides a new view, Malloc Error View, that lets you focus on malloc errors without having to sort through legitimate malloc operations. Malloc Error View is available when you perform the "Find Memory Leaks" task. It takes the same form as Malloc View--the difference is that where Malloc View displays all mallocs in its list area (the upper pane), Malloc Error View displays only mallocs or frees that caused errors identifying the cause of the problem and how many times it occurred. Malloc Error View replaces some of the functionality of Heap View. When you run a "Find Memory Leaks" experiment and the Performance Analyzer detects a malloc error, a dialog box will display recommending that you use Malloc Error View to analyze the results. o The "Find Memory Leaks Task" task has four associated performance metrics available. The leak counts were previously on by default--the malloc counts are now turned on as well. The metrics are: - Inclusive Bytes Leaked - the number of bytes leaked from this function (including any called functions). This metric can be turned on for arcs as well as functions. - Exclusive Bytes Leaked - the number of bytes leaked from this function (excluding any called functions). - Inclusive Bytes malloc'ed - the number of bytes malloc'ed from this function (including any called functions). This metric can be turned on for arcs as well as functions. - Exclusive Bytes malloc'ed - the number of bytes malloc'ed from this function (excluding any called functions). - 6 - o There is a new task called "Get PC Sampling Times". It has no new functionality. It simply lets you perform statistical profiling with fine grained usage sampling at 1-second intervals without capturing any other performance data. It only works on 64-bit processes. o The "Determine bottlenecks, identify phases" task and the "Get Total Time per function & source line" task both capture Call Stack Profiling data every 100 msec. by default. o I/O tracing has been incorporated into Syscall Tracing. When you perform Syscall tracing experiments, you can now get read and write counts and can display I/O View. o If you prefer to sort by exclusive rather than inclusive data by default, you need to set cvperf*emphasizeExclusive to TRUE in your Xdefaults file. o The following environment variables are available for "Find Memory Leaks" experiments: - MALLOC_VERBOSE - MALLOC_TRACING - MALLOC_FASTCHK - MALLOC_MAXMALLOC - MALLOC_NO_REUSE - MALLOC_CLEAR_FREE - MALLOC_CLEAR_FREE_PATTERN - MALLOC_CLEAR_MALLOC - MALLOC_CLEAR_MALLOC_PATTERN These are described in detail in the reference (man) page for MALLOC_CV. 3.5 Integration_with_other_Tools WorkShop includes facilities for integrating with other tools. The WorkShop tools can be started from other WorkShop tools by using the "Launch Tool" sub-menu under the "Admin" menu. You can add entries to the "Launch Tool" menu - 7 - by adding lines to the file /usr/lib/CaseVision/system.launch. The format of the entries in this file is the menu entry, followed by a comma, followed by the command line that should be run to start the tool. 3.6 Integration_with_Cadre_teamwork The CASEVision/WorkShop "Launch Tool" menus can be combined with teamwork's User Menus to provide a tight coupling between the CASEVision/WorkShop tools and Cadre teamwork tools. 3.6.1 Starting_teamwork_from_CASEVision/WorkShop Adding the following line to the file /usr/lib/CaseVision/system.launch Teamwork, /cadre/tsa/com/teamwork will provide an entry labeled "Teamwork" in the "Launch Tool" sub-menu of the "Admin" menu of the WorkShop tools. Selecting this menu entry will start up teamwork. 3.6.2 Starting_WorkShop_tools_from_teamwork Here is a sample teamwork User Menu file for the CASEVision/WorkShop tools: # CASEVision/WorkShop User Menu Definitions (Menu (Name "WorkShop") (MenuItem (Name "Debugger") (Action (SysCall "../../../usr/sbin/cvd")) ) (MenuItem (Name "Build Analyzer") (Action (SysCall "../../../usr/sbin/cvbuild")) ) (MenuItem (Name "Parallel Analyzer") (Action (SysCall "../../../usr/sbin/cvpav")) ) (MenuItem (Name "Performance Analyzer") (Action (SysCall "../../../usr/sbin/cvperf")) ) (MenuItem (Name "Static Analyzer") (Action (SysCall "../../../usr/sbin/cvstatic")) - 8 - ) ) By including these definitions in a user menu file, you will be able to start up any of the CASEVision/WorkShop tools directly from the teamwork tools. - 1 - 4. Bug_Fixes This chapter lists the bugs that were found in WorkShop 2.2 and fixed in WorkShop 2.3. 4.1 WorkShop_Debugger 179070 1st invocation of cvd --> ttutl: Couldn't connect to ttsession err 191451 Expression view give error when evaluating 2d array element. 211058 2.2 MR: cvmain core dump 212856 cvpcs incorrectly lists base classes. 215845 Source editor doesn't save file on a full NFS filesystem 218450 cvd core dumps when loading application build with CC. 218754 BUG WorkShop Performance task hangs 219683 cvpcs died: -non_shared binaries are not supported. 221202 BUG - core dump in cvd 221388 cvd core dump when doing "print *this" 221569 cvd core dump when printing a template variable 222118 cvd step behavior is wrong in f77 program 222303 cvd exit abnormally when printing the value of a char string 222632 cvd core dump with message "loss contact with the process control server" 223681 cvstatic crashes when trying to "print *this" 228760 Can't make interactive function calls 228765 SDRC can't attach to geomod.exe 214158, 226081 Evaluate Expression dialog box ignores autoStringFormat. - 2 - 226877 Array Browser Spreadsheet loses cell display. 229275 Array subscript control slider doesn't work in array visualizer view. 229572 cvpcs core dump in InterpreterF77::openFile. 206140 cvd Variable Browser does not list Fortran COMMON block values 218756 cvd/delta - pcs core dump on p *this in class which has anon union. 217188 cvd crashes during disassembly when given a text label. 217285 cvd dumps core when accessing address of symbol from Memory View. 207481 cvpcs F77 expression memory leaks. 207975 cvpcs/dso cannot handle two loaded copies of a dlopen()ed dso. 209636 PCS aborts if user program mmap()s a Delta-C++ .o file. 210354 cvpcs core dump. 211185 cvpcs/eval cvpcs internal_error() in set_array_type_size(). 211393 cvpcs core dump trying to print a global. 211947 cvpcs dies going to line in file (Delta code). 211987 cvpcs dumps core. 212504 Watchpoints do not work watchpoints latest cvpcs. 213372 cvpcs core dump while trying to step into a function. 213472 cvd claims a non-stripped executable (NCC compiled) is stripped. 213530 cvpcs coredumps on NCC-built cvstatic. 214077 cvpcs coredumps debugging NCC-built cvstatic. - 3 - 214386 Step Over random behavior. 213471, 214119 cvpcs core dump WkShp 2.2 C++ code. This bug has been partially fixed. 207486 cvpcs Edg expression evaluator memory leaks. 207487 cvpcs symbol table memory leaks. 160162 cvdb files built with wrong umask. 208322 Two constr calls are reported for 1 instantiation. 208326 unimple sym kind mesg when calling undecl func. 224065 cvmon core dumps when handling target program fork/execs a nonshared program. 4.2 WorkShop_Static_Analyzer 178076 cvstatic eats all remaining disk space when file not found 185977 Core dump during query which forced compile revealing source error 212515 cvstatic "Set Include Path" does not work for Fortran INCLUDE statement 218433 cvstatic -SCANNER doesn't locate typedefs and struct defs 230464 During compile, cvstatic uses all available disk space, then crashes 89655 cvstatic - duplicate keyboard accelerators. 129191 cvstatic should be case insensitive when querying Fortran code. 201535 cvstatic automatic alternate fileset for read-only filesystems. 205944 call tree is not displayed. 206211 cvstatic file set scanner to parser transfer takes minutes. 206502 cvstatic - f77 -sa does not build .o's and executables as it should. - 4 - 210194 cvstatic - "List Global Symbols" fails to work with Fortran code. RFE Should be able to easily add options, like adding include dirs. 209629 Static Analyzer/C++ Browser doesn't work on C++ headers. 210652 cvstatic - C++ Browser disables its own menu item. 211937 C++ Class Browser fails to parse file. RFE C++ class browser Interaction graph arrow actions. 207152 cvstatic/NCC: Internal Error: Array size 16, attempted to access 22 element. 208016 cvstatic parser mode fails with certain code declaration. 4.3 WorkShop_Performance_Analyzer 184680 cvperf needs to set busy dialog, and inform the user of progress 205950 CPU times are incorrectly displayed in source view 206395 cvinstr dies silently if it runs out of disk space 210443 cvperf core dumps on experiment with DCC-built executable 210832 libmalloc_cv[_d] doesn't know about memalign! 215114 Problem mixing valloc and libmalloc_cv[_d] 224541 cvinstr fails if >32000 instrs. in one basic block 226959 cvperf core dumps when asking for numerical usage view 227847 Delay load causes malformed experiments 228755 Various instrumentation problems - 5 - 4.4 WorkShop_Tester 186699 cvxcov help menu doesn't match the rest of the WorkShop help menus 187217 cvxcov aborts sporadically on runtest 187218 cvxcov can't run tests when $SHELL=/bin/ksh 189649 License warning for WorkShop Tester should refer to WorkShop 189651 cvxcov core dumps on simple query when no test loaded 189653 cvxcov core dumps when I make a test, delete it, and remake same test 189654 cvxcov core dumps trying to List Function created/delelted/recreated test 189656 cvxcov core dumped in two ways when trying to reload test described in 189653 189717 cvxcov disassembly view takes an inordinate amount of time for average file 192244 Status of process is incorrect 194174 core dump in XFindContext, sgiMode:True only 204757 cvcov does not set branch count flag in USER_SELECTION file 206130 cvcov/cvxcov: Symbol resolution algorithm is not correct 221315 cvcov mktset -list: made test set without any subtests. - 1 - 5. Known_Problems_and_Workarounds 5.1 WorkShop_Debugger o The ability to unwind the call stack using the Call Stack View does not work reliably. Stack traces will be incomplete when stopped in a signal handler of a 4.X binary running on a 5.X or a 6.X system. Returning from the signal handler using "step into", "step over" and "return" will not work correctly. Similarly, registering a signal through sigaction call with the SA_SIGINFO flag set may cause incorrect stack traces when stopped in the signal handler. (Incident #215151) Workaround: There is no good workaround for this problem. o The Debugger has trouble determining if a core file and executable match when the executable is Elf non-shared. If this problem occurs, you are likely to receive an incorrect stack trace without any warning that the core file may not be based on the given executable. o The views that do expression evaluation, Expression View, the Evaluate Expression dialog box, Structure Browser, Variable Browser, Array Visualizer, and the Debugger command line cannot yet evaluate: - long double (C/C++) and unsigned variants - real * 16 (Fortran) and unsigned variants - complex *32 (Fortran) and unsigned variants Evaluation of these types will not be available until the WorkShop 2.4 release. (Incident #206313) o Nested struct members cannot be printed when the executable is compiled with NCC/DCC (C++) compilers on a 5.X system or as 32 bit C++ executable on 6.0 systems. (Incident #207701) o Fortran programs with multiple definitions of an alternate entry point can cause debugger core dumps. Workaround: Remove the duplicate alternate entries. (Incident #210757) o Fortran pointer based variables cannot be evaluated for Mips3 and Mips4 executables due to a lack of symbol table information. (Incident #208584). - 2 - o Making an interactive function call when the target process is sleeping in a system call will cause the target to fault. (Incident #223601) o WorkShop does not accommodate text editors other than Source View very well. Workaround: Set the editorCommand resource in the app-defaults file to your desired editor. For example, set editorCommand to wsh -c vi +%d to run vi in a wsh window. You also need to set *useToolTalk to False. o If you set traps with the Debugger and subsequently rebuild the target using Build Analyzer, the traps will be lost in the new version. Workaround: Save the traps using the "Save Traps..." selection in the Config menu in the Traps Manager. After the rebuild, use the "Load Traps..." from the same menu to restore the traps. You should then check that all traps are in the proper location in case a change in line numbers has caused problems. o If you run Expression View and select "Bit Size" from the Format menu, the results are incorrect. Workaround: Multiply the results number by 8. o The Debugger occasionally dumps core if you try to use traps using the "Load Traps..." selection in the Config menu in the Traps Manager. Workaround: Restart. o The Value field in the Evaluate Expression dialog box does not display 64-bit addresses for MIPS3 and MIPS4 executables when you select the "Address Of" menu item in the Format menu. (Incident #229960) o The request to kill a process which has spawned child processes (through fork(), sproc(), or sprocsp()), followed by exiting cvd, may not properly terminate the descendant processes. The descendant processes may continue to run after cvd has exited. Workaround: Kill all of the process group members with the Multiprocess View as opposed to using the Main View. If any of the descendant processes were created through a fork(), you will have had to direct the Multiprocess View to attach to fork()ed process (see ``Config: Preferences'' in the Multiprocess View). - 3 - o The Multiprocess View is known to occasionally not display all process group members. One condition where this problem occurs is when the list of processes shown by the Multiprocess View is frequently changing in a short span of time (for example, processes are fork()ed which exec() and exit shortly after they start). Workaround: Use of Stop in the Multiprocess View will cause cvd to stop all process group members and the display should change to correctly list all processes. o When cvd is brought up on one member of a running shared process group (see sproc(2)), cvd does not identify all of the other processes which are members of the shared process group. If you start up the Multiprocess View you will only see the process you started cvd on. The correct behavior from the Multiprocess View would be to display all members of the shared process group. Workaround: Use ``Process: Add'' in the Multiprocess View to manually add each member of the shared process group to the cvd process group display by Multiprocess View. (Incidents #219937, #159616, #168934) o Disassembly View sometimes has problems when two or more DSOs have overlapping text. In such cases, Disassembly View displays only one of the DSOs from the set whose text overlaps. This can happen to users who are building their own DSOs. Unfortunately cvd does not warn the user when this type of conflict occurs. The problem will manifest itself when you create a source level breakpoint (trap on entry/exit to a function or on a source line). While you may request that cvd trap on line N of file F, cvd may come back and claim to have set a trap somewhere else. This is primarily a display problem; the trap will be set correctly when you request to run the program. Workaround: Define a trap on entry to main and run the program. Once the process stops on entry to main, define any additional traps. You will find that all traps are defined and displayed correctly. o On attempting to locate the DSOs used by an executable, cvd uses the shell environment in which cvd was started, as opposed to the shell environment within the Execution View. This means that the value of environment variables like LD_LIBRARY_PATH which are used by cvd may not match the values in the shell where the executable will be run. When cvd is using the - 4 - wrong values for environment variables like LD_LIBRARY_PATH, it may have trouble finding all of the appropriate DSO symbol tables. When cvd has trouble finding DSOs used by an executable it will display the Library Search Path dialog to call attention to the DSOs which could not be found. Workaround: Use ``Admin: Library Search Path ...'' to examine and set environment variables like LD_LIBRARY_PATH which control the identification of DSOs. o Watchpoints in cvd may be defined with an address and size or an expression. If you attempt to watch an expression which resides on the stack (for example, a local variable) cvd will not allow definition of the trap. cvd will only watch expressions whose location is within a mapping other than the stack. Workaround: If you want to watch an expression which resides on the stack, use the expression evaluator to find the address of the expression and create the watchpoint using the address. Once the expression is deallocated, the watchpoint should be removed to avoid any confusion when the stack address is reused for some other purpose later on in the execution. o Process group watchpoints involving expressions are not supported well. If you create a watchpoint with a command like pgrp watch , the expression is only evaluated once on one of the process group members. The evaluation is used to determine the address and size of the watchpoint, and address and size is used on to create a watchpoint on each process group member. This will only work correctly if the address of size of the expression is the same for each process group member. There is no workaround known for this problem. o cvd does not have support for weak symbols (see Appendix A of the C Language Reference Manual). cvd will not recognize the weak symbol name. For example, cvd will not accept a request to trap on entry to dlopen. Workaround: Use the "strong" symbol name in place of the weak one. Many weak symbols defined in libc have corresponding "symbol" symbol names which are the weak name with a ``_'' prepended onto the front. For example, the "strong" symbol name for dlopen is _dlopen. - 5 - o A write watchpoint may fail to fire when the write occurs within a syscall. For example, a write watchpoint on one word within a buffer written by read may fail to fire. Workaround: Define the watchpoint to cover the entire data structure as opposed to a subset of the structure. For example, define the watchpoint over the entire buffer being handed to read as opposed to a single word. o An attempt to step into the first call to an external function will behave like a step over. The first call to an external function invokes rld to resolve the function address. When this occurs the request to step into the call will look like a step over to the user. Workaround: Either set the environment variable LD_BIND_NOW to 1 in the Execution View prior to running the program (see rld(1)) or use function entry breakpoints. o The Fortran intrinsics char, zext and the intrinsic subroutine extensions documented in the Fortran 77 programmer's guide are not supported. o The debugger does not understand external or intrinsic statements in the Fortran program. If the program has a function by the same name as an intrinsic function, evaluating an expression involving that function will always cause the program function to be called. o Some of the intrinsics (sqrt, exp, log, log10, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh) do not give the correct results when the debugged executable is linked with libm.so. This is because of entry points with similar names in libm.so. Workaround: Use a specific intrinsic name. For example, sin(r1) where r1 is real will produce incorrect results. On the otherhand, dsin(dfloat(r1)) will give correct results, with the results being a real *8 quantity. o Stopping in the entry prologue of a function (before the first user statement) in a Fortran program and evaluating an expression that involves an adjustable array will not work correctly. Workaround: Step to the first user statement and evaluate the expression. - 6 - o Stopping in the entry prologue of a function (before the first user statement) in a Fortran program and displaying an adjustable array in the Array Visualizer will cause cvarray to hang or core dump. Workaround: Step to the first user statement and display the array. o When stopped in a Fortran function/subprogram that has alternate entry points, the debugger will not list all the arguments of the subprogram and their values correctly. o For global lookups, cvd acts as though all DSOs are built -B symbolic. If a process is stopped within a DSO and the user asks cvd to lookup a global variable or function, cvd will always look within the DSO before it considers the main program or any other DSO. In effect, cvd is acting as if each DSO has been built with -B symbolic. o The Array Visualizer will freeze the mouse if the target process is terminated or goes to completion while the render view is up, and the user clicks on the right mouse button in the render view window. The system is not hung but the mouse stays frozen until the cvarray process is killed. o The slider bars in the Subscript Panel of the Array Visualizer have been deactivated and cannot be manipulated by the user. o Occasionally, the debugger cannot dereference class member pointers. Workaround: Cast the pointer value to the appropriate type, and dereference it. o Interactive calls to inline member functions of C++ classes is not supported. o There is no support for C++ overloaded operators in the expression evaluator. o The debugger does not have full support for C++ templates. However, the user can stop in template code and print the ``this'' pointer. o The display format for describing an array pointer types is incorrect. For example, an array of - 7 - double(*)[2] is expressed as double[]*. o Elements of Fortran arrays with more than 6 dimensions (or 5 dimensions, if the element type is character string) cannot be referenced. o Fields in anonymous unions do not display correctly in the expression evaluator. o C++ objects containing virtual base classes do not display correctly in the expression evaluator. o cvpcs may core dump if an expression involving a C++ object is evaluated, while stopped in an ANSI C function. o cvpcs can stack trace through assember alternate entry functions only when they are at the same address as the main entry point. Assembler functions with arbitrary alternate entry points will produce incorrect stack trace. o When the Trap Manager is invoked, traps are automatically loaded from the .cvTrapMgr file if one exists. However, these traps are reloaded if the Trap Manager is closed and restarted. Workaround: The Trap Manager should either be left running or the default traps should be stored in a different file and reloaded manually when desired. o In general, when a write watchpoint fires, the write is simulated by the debugger to show the new value before any trap conditional is evaluated. The one exception for this case is the SC instruction, which is present only in the MIPS-2 instruction set and is not generated by the compiler. In the case of handwritten assembly code that uses this instruction, the write is not simulated. o A kernel bug prevents watchpoints from firing reliably for members of share process groups (such as Power Fortran or Power C programs). Watchpoints work reliably for non-shared text and data segments in each individual process. o If you stop a process through job control, the debugger may not display an accurate status of the process, and process control requests do not take effect until the process is resumed through job control. A process is stopped through job control with from the - 8 - shell or when it receives one of the signals: SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU. A process is resumed through job control with fg and bg from the shell or when it receives the signal SIGCONT. If a running process is stopped through job control, the debugger continues to show that the process is running. When attaching to a process stopped through job control, the debugger shows that the process is stopped. o The Step Over command, Return command, and interactive function calls are disabled for instrumented executables. These features are not available when doing performance analysis and are limited to debugging non-instrumented executables. o For instrumented executables (used for performance analysis), stack frame unwinding may be incomplete when stopped in a signal handler; the unwinding may stop prematurely after the ``_sigtramp'' frame. Workaround: A full stack trace may be maintained by returning past the ``_sigtramp'' frame. o The demo program jello cannot be built as described in the tutorial without the library /usr/lib/libgl.so. Workaround: This library should be installed when IRIX is installed (eoe1.sw.gfx_lib subsystem). o Processes that use the blocking capabilities as provided by blockproc(2) may not terminate as expected upon completion of a debug session. Such processes are left in a blocked state with a SIGKILL pending. Workaround: These processes can be terminated with kill(1). o The modification of an inactive trap will cause the trap to become active. You will have to toggle the active button next to the trap description in order to deactivate the trap. o There is a case where the path remapping component of WorkShop will find the wrong file. When cvd is stopped and started multiple times, and ``Admin:Exit'' was used to exit cvd, the path remapping component will retain entries in its Substitution Set from each debugging session (see ``Admin:Project:Remap Paths...''). The path remapping component of cvd is implemented as a separate process and the ``.'' entry in the Substitution Set refers to the directory in which the - 9 - process was started, typically the directory were the first cvd was started. Workaround: Use ``Admin:Project:Exit'' in place of ``Admin:Exit''. This will force the path remapping process to terminate on each exit of cvd. o By default the debugger will not attach to a fork()ed process unless the fork occurs during an interactive function call. If you have used the Multiprocess View preferences dialog to prevent a forked child from being resumed, and you make an interactive function call will leads to a call on fork, the child process will be left stopped on exit from fork. You must now use the Multiprocess View to resume the child process. o The debugger may erroneously claim that a source file from a DSO is newer than the executable. While a source file may in fact be newer than the executable, what is really relevant is whether the source file is newer than the DSO. The user should not always take these warnings seriously. Users who build their own DSOs may rebuild a DSO without rebuilding the executable. In such cases warning the user that a source file is newer than the executable is of little value. o When using the Query menu within cvd to make cvstatic queries, if the query has multiple answers, cvd issues two warnings. The first warning is about multiple answers and is correct. The second warning about results not being found is wrong and should be ignored. It simply means that the results will not be displayed in the cvd source view window. Workaround: To ask queries with multiple answers, use cvstatic's own Queries menu and see the multiple results displayed there. o In the Variable Browser view, Fortran COMMON block values are not listed. o Fortran COMMON block members that are at an offset greater than 8 Megabytes from the start of the common block will not be evaluated correctly in an expression. o When using the Switch Process dialog to attach to an existing process, don't attach to one of the CASEVision processes (e.g. cvmain, cvpathRemap) or the environment may hang. Should this happen, kill the cvmain process - 10 - and start over. o Occasionally, cvmain will dump core at startup if you have an executable with a mismatched core file and your NetLS license is within 90 days of expiring. If this happens, restart cvd. o The request to print the content of a very large data structure (such as an array) from within the main window's command line interface panel may lead to an abort of cvd. Workaround: The Array Browser may be used to display very large arrays. o The main window's command line interface panel will only display the first 100 elements of an array. There is no way to change this behavior. Workaround: The best way to examine an array is the Array Browser. o Very infrequently the process being debugged gets killed when you press ``Run''. If this occurs, a warning popup will tell you to look at the Execution View where you will see that cvxhang has failed. Workaround: Press ``Run'' again. 5.1.1 Debugging_Program_Groups_Including_a_Set-uid_Program Because of standard IRIX security policies, the debugger can not debug a program running as another user (unless you are logged in as root). This restriction applies even to system programs which are set-UID, and even when all you want to do with the set-UID program is debug something that it in turn runs. It is common to use the system-provided set-UID program xwsh (or winterm, which in turn runs xwsh) in this way. There are two basic ways to deal with this problem. You can become root before starting your debugging session, which grants you all necessary access rights (but may be infeasible for your application or situation). Or, you can arrange to use a non-set-UID copy of the intermediary program, for example with chmod, or by making a copy of the program with cp. There is also a bug in the IRIX 6.0 version of xwsh which makes it unreliable if run non-set-UID. You may be able to use xterm instead of xwsh for these applications, for example by using winterm and setting the environment - 11 - variable WINTERM to xterm before starting your debugging session (and providing a non-set-UID copy of xterm). If your application depends on features of xwsh, can not use xterm instead, and can not be run as root, then this procedure will generally ensure that you can debug as non- root: o Make a non-set-uid copy of xwsh (cp /usr/sbin/xwsh .). o Start several xwsh or xterm windows, as the user who will be doing the debugging. Exit them all. It is important that they all be started together, all be running at once, and then be exited immediately before the debugging session begins. o Debug your application. o Set one or more breakpoints by function name ("stop in main"), in the syscall panel, or with the ``Traps: Stop at Function Entry'' menu - not by clicking in the glyph bar of the main window. (Traps set on a particular source line, as by clicking, are not copied from one program to the next.) o Bring up the MPView, from the Admin menu. o Be sure all the "copy traps...." boxes are checked in its configuration dialog. o Run your application, using MPView's ``Continue'' button as necessary and watching MPView for the appearance of your subprocess. Double-click it to launch a debugger on it. 5.2 WorkShop_Build_Analyzer If target or dependency names are specified using parentheses to denote files stored within an archive library, cvbuild will use a single node to represent the archive library, rather than individual nodes for each file within it. 5.3 WorkShop_Static_Analyzer Important note: cvstatic's scanner mode is based on a sophisticated pattern matcher. It works by searching for and identifying common patterns that occur in programs. Both philosophically, and in terms of the actual - 12 - implementation, cvstatic is most closely related to the program grep. If you expect cvstatic to produce the type of results that can be accomplished only with a full- compilation type of analysis, you should use the new compiler-based parser mode. If you approach cvstatic's scanner mode as a ``super-grep'', using it as most programmers currently use grep (or various ``tags'' packages) to explore a new program, you can quickly get a quick high-level look at your code. Many of the limitations and shortcomings mentioned below are a direct consequence of the grep-like model supported by cvstatic's scanner mode. However, in all cases, cvstatic provides a more powerful way to approach understanding a set of source files than merely using grep. 5.3.1 Size_Limitations o When using cvstatic's Fileset Editor to add entire directories of files, cvstatic limits the number of files to 10,000. This limit exists to prevent someone from inadvertently starting at the root of a file system and trying to add all files. Workaround: There is no limitation on the number of files that can be added to the fileset when the fileset file is constructed in other ways, such as compiling source files with the -sa flag, or emitting a fileset from a Makefile rule. o cvstatic displays at most 20,000 lines of unfiltered results from a query in the Text View. Workaround: Larger results may be saved to a file, or reduced to a more manageable size using the Results Filter. o cvstatic displays no more than 5,000 functions in the Call Tree View, 10,000 files in the File Dependency View, or 10,000 classes in the Class Tree View. These are absolute maximum limits, and the actual limits may be much lower depending on characteristics of the graph being displayed. In particular, all graph views in cvstatic are displayed in a scrolled X window, which is sized to accommodate the graph. X imposes a maximum size on windows, and graphs cannot exceed that size. Workaround: Use more specific queries to focus on the part of the program that is of the most interest. Reduce the scale used to view the graph. Use the - 13 - Results Filter to prune the results of Queries. Use the graph views' Incremental Mode setting, or the pop- up menus on nodes of the graph, to follow a specific path through a large tree. 5.3.2 General_Known_Problems o The cvstatic query "Where Type Used" does not return any results in C programs analyzed in parser mode. (Incident #228689) Workaround: Use the "List Data of Type" and "List Functions of Type" queries. These queries will still not show other uses of a typename, such as in cast expressions and sizeof expressions. The General Query string search can be used to find the remaining uses. o The WorkShop manual in Chapter 3, Tutorial 3, shows how to use the compile driver command to generate a cvstatic database by using the -sa flag. In Irix 6.0, the 64-bit fortran compiler f77 does not accept this flag. Workaround: The old 32-bit fortran still accepts the flags -sa and -nocode. You can still create cvstatic databases through the cvstatic gui, or add extra rules to your makefile calling the /usr/WorkShop/usr/bin/f77 driver directly. This driver makes databases but does not generate code, and so can be added to a Makefile without overwriting any .o files. o If you use cvstatic to analyze a fileset and then change one or more of the header files included by the files in the fileset, rescanning the fileset will not detect the change. Rescanning only detects changes to source files listed in the fileset. Similarly, if you remove a source file from a fileset and rescan, the header files included by that file are not removed from the database. (Incident #179731) Workaround: If you have changed one or more files in a fileset (or included by files in a fileset), you can get a consistent database by selecting ``Force Scan'' from the Admin menu. o Some printers may clip the output when printing a PostScript version of graph saved by cvstatic. Workaround: None, except trying another printer. - 14 - 5.3.3 Known_Problems_with_Mixed_Languages o If you analyze a program that contains both Fortran and C routines, cvstatic in scanner mode does not recognize that the C function foo_ and the Fortran function foo refer to the same routine. In parser mode, cvstatic will identify the routines correctly, if it analyzes the C file containing foo_ before the Fortran file that calls foo. So, make sure that your C files appear earlier in the fileset than your Fortran files. - 15 - 5.3.4 General_Known_Problems_in_Scanner_Mode o In general, cvstatic does not require code to be able to be compiled. cvstatic should provide useful information even when code has syntax errors. However, there are several requirements that must be met for cvstatic to work properly. In C and C++, cvstatic relies on the existence of matching braces to determine the beginning and ending of blocks and bodies of functions. In Fortran, cvstatic relies on the existence of matching end statements. Functions without closing braces, or end statements, or code with too many end statements or mismatched braces can cause unpredictable results. In C, it may be necessary to use cvstatic's -preprocess option with heavily ifdef'd code to achieve matched braces. If any of these limitations of scanner mode keeps cvstatic from being useful, using parser mode may be the right solution. o cvstatic accepts regular expressions in nearly all fields. This can occasionally cause problems if you unintentionally use a pattern without realizing it is a regular expression. For example, specifying a filename of foo.c++ usually fails, because + is a special character in regular expressions. Workaround: Backslash all regular expression special characters when not used to specify a wildcard pattern. For example, the filename mentioned above would be entered as foo.c\+\+. o The cvstatic Variable query, ``Who Sets'' recognizes only variable assignments that use ``='' to assign directly to a variable. This query does not recognize or account for aggregate initialization statements in C or C++, references in C++, assignments made as a result of passing or operating on pointers in C, or data, equivalence, common, or assign statements in Fortran. Workaround. Use ``Who References'' to see all locations in which the variable is used and to visually inspect for assignments. o By default, cvstatic does not honor ifdef's in source code. Much of the time, this is desirable behavior. cvstatic allows you to find all references that satisfy a query. However, this may result in an incorrect or misleading function call tree. Heavily ifdef'd code may - 16 - also confuse cvstatic, because (in C) cvstatic relies on matching braces to detect the end of functions. Workaround: Use the -preprocess flag when starting cvstatic. This makes cvstatic run much more slowly, but it honors most ifdefs. o cvstatic recognizes many common C, C++, and Fortran language patterns. However, all three languages allow programmers to write code that is not easily identified by patterns. Workaround: If you find that cvstatic misses or misidentifies parts of a program, you can usually resort to string, regular expression, or symbol queries to find the information you are looking for. o Files containing very long lines are not handled in scanner mode. If a file contains any line longer than 3000 characters, cvstatic's scanner will fail. Workaround: Use parser mode, or shorten your source lines. 5.3.5 Known Problems Using cvstatic in Scanner Mode with C++ cvstatic analyzes C++ source code much more accurately in parser mode than in scanner mode. The following problems are known to occur in scanner mode. They can be avoided by following the workaround suggestions, or by using parser mode. o cvstatic does not do macro expansion, so classes based on macros used to simulate C++ parameterized types are not detected. o cvstatic does not completely handle function calls made through function pointers, in C or C++. In C++, this includes calls to member functions made through object pointers. For example, consider the following code segment: samplefunction () { A *object1 = new A(); B *object2 = new B(); object1->func(); object2->func(); } In this example, cvstatic correctly reports that samplefunction() calls func() two times. However, it - 17 - cannot determine that these two function calls are actually made to two different member functions, implemented by two different classes. Similarly, cvstatic does not know about the this pointer. Workaround: Don't try to display full function call trees for C++. Instead use queries like ``Who Calls ''or ``Who Is Called By '' which produce meaningful results. o cvstatic does not understand overloaded functions. Workaround: Use the text view for all queries involving overloaded functions. o C++ allows extensive use of operator overloading, which allows you to write code that can obscure what is really happening in the code. Because cvstatic is designed around a pattern matcher, novel constructs produced by overloading operators are not normally detected. Constructs that conform to normal language conventions should normally be found. For example, if A and B are objects, and the ``='' operator has been overloaded to indicate an assignment of the contents of object B to the contents of object A, cvstatic should be able to handle this situation. However, if some unusual overloading conventions have been used (say, using ``[]'' to mean a function call), cvstatic does not show the same results as the C compiler. Workaround: If you have such code, use string or regular expression searches, or symbol searches to find what you are looking for. o C++ programs containing templates are not well understood by scanner mode. Workaround: Use parser mode. 5.3.6 Known_problems_Using_cvstatic_with_Fortran cvstatic analyzes Fortran source code much more accurately in parser mode than in scanner mode. The following problems are known to occur in scanner mode. They can be avoided by following the workaround suggestions, or by using parser mode. o cvstatic occasionally misses function calls and other statements that directly follow an if statement on the same line. o cvstatic uses a pattern matching approach. This approach does not allow the tool to detect the - 18 - irregular use of spaces within Fortran symbols, even though these are allowed by the Fortran compiler. For example, the Fortran compiler accepts the statement: sub routine my 1func tion as if it were written: subroutine myfunction cvstatic does not handle such conventions. Workaround: None in scanner mode. Silicon Graphics strongly suggests changing such code to use a more readable coding style. o cvstatic does not support the use of Fortran keywords for uses other than their intrinsic function. For example, cvstatic always recognizes word ``if'' as starting a conditional statement. Programs that use ``if'' as a variable or function name are not analyzed correctly. Workaround: None in scanner mode. Silicon Graphics strongly suggests changing such code to use a more readable coding style. o In some situations, cvstatic can mistake references to arrays as function calls. This is particularly true when the Fortran code relies on include files to declare arrays, common blocks, and so on. cvstatic does not analyze header files at the point at which they occur, but simply adds them to the list of files to be analyzed. This contributes greatly to the speed of cvstatic, but means that cvstatic does not have various type declarations available to it. Because Fortran arrays cannot be differentiated from function calls without a declaration, cvstatic identifies arrays not defined in the file in which they are referenced as function calls. Workaround: Use the Results Filter to exclude ``external'' functions. This limits all queries to those functions actually defined in the fileset. Excluding external functions hides all array references erroneously identified as function calls, but also hides all calls to library functions, intrinsic functions, or other routines declared outside the fileset. - 19 - 5.3.7 Known_Problems_Using_cvstatic_in_Parser_Mode o cvstatic assumes that filenames ending in .c are C files. Workaround: If you give C++ files the .c extension, you must also manually edit your fileset file to replace ncc driver with NCC. o Mismatched member function declarations and definitions are not recognized by cvstatic's parser. The parser runs into trouble processing a member function if the signature of its declaraction and definition are not identical. For example, if the code contains something like this: typedef int* intptr; class A { public: A (int * i); }; A::A (intptr i) { } the parser will print the error message "no record for method A::A?" and terminate processing of the file. Workaround: analyze code like this in scanner mode, or change the type signatures so that the definition and declaration match. o cvstatic's parser mode is better at building a new database than at modifying an existing one. If you build a parser-mode database and then change a file and reparse it, the database will grow each time you rescan the file. Not all space is reclaimed. Additional arcs may appear in the Call Tree view representing defunct call site information. Workaround: After a few files are modified and re- analyzed, it is best to use Force Scan to rebuild the entire parser-mode database. For a large code base that is slow to parse, you can use the -batch flag to rebuild the database overnight. o Functions generated by templates are recognized and displayed by cvstatic, but it treats them as external functions: functions that are declared or used within the fileset but are not defined there. Consequently, - 20 - they do not appear in the results of the ``Query List All Functions''. Workaround: Use specific queries about these functions, like ``Where Function Called'', or add them manually to Call Tree graphs. o The function "main" appears in the list of Functions Not Called, if it is not called explicitly from the source code. ("main" is rarely called explicitly.) Workaround: You can add the function "main" manually to any graphical display of functions. o Graphical display of a single member function called through derived classes is incomplete. If a C++ member function Foo::Func is called through classes derived from the class Foo, each derived function Func will appear as a separate function in the Text View list of functions. However, only one node will appear for Func in the Call Tree View. Workaround: To see the full list of definitions and calls of Func, use Text Mode. If you double click on the definition of one of the derived Funcs, you will navigate either to the defintion of the function (if you click on the version in Foo), or to the definition of the derived class through which Func was called. o If you analyze Fortran sources by running the compilers directly with the -sa switch (as opposed to having cvstatic analyze them for you), you may see the error message: *** db_VISTA database error -4 - invalid database when the first file is analyzed. This does not indicate a problem; it just means that no database was found by the front-end, and so it will go get an initialized database to use. The results in the database will be correct. o If you are analyzing C++ code in which multiple non- member functions have the same name, cvstatic will think they are all the same function with one definition and several declarations. Workaround: You can get to the definitions by using the ``Where Defined'' and ``Where Declared'' queries on functions. - 21 - o When you first bring up cvstatic, if you switch the view from Text View to a graph view before building the parser database and doing your first query, the graph may incorrectly display as empty. Workaround: Stay in Text View to perform your first query, and then switch to whichever graph view you wish. Or, if you have already brought up cvstatic in a graph view and built the database, hit ``Rescan'' in the Admin menu, and then redo your query. o cvstatic confuses the difference between declarations and definitions. For example, if you have three functions named foo, only one definition site is reported by ``Where Defined'', while the other two sites are reported by ``Where Declared''. Workaround: Use both queries to find all definition sites. 5.3.8 Admin_C++_Browser_Menu_Item The Admin menu includes a button for the C++ Browser, which is part of a separate product, WorkShop Pro C++. You need a separate license to enable this capability. To obtain the license: Call 415-390-1935 (US) or email cv@sgi.com 5.4 WorkShop_Performance_Analyzer o The ability to show the call stack using the Call Stack View does not work for some functions in libc and most assembly routines (64-bit). (Incident #226601) Workaround: There is no good workaround for this problem. o I/O tracing and system call tracing is very exepnsive in termsof the quantity of data captures and for 64-bit programs does notproduce useful data due to call stack unwind problems. We do not recommend running these types of experiments for this release. o 64-bit malloc/free tracing also have similar call stack problems. o Malloc/free tracing experiments on programs that fork may produce misleading data. For example, a child - 22 - process may free a block allocated in the parent, which will appear as a bad free. (Incident #202710) o Malloc/free tracing experiments on programs may report spurious bad free and realloc errors when the timeline calipers are set less than the full period of the experiment. (Incident #231453) Set the calipers to the full length of the experiment when examining these types of errors. o The cursor in the Performance Analyzer occasionally displays as a wristwatch after control has passed back to the user. You can simply ignore the form of the cursor. (Incident #231808) o During instrumentation, the program cvinstr might run out of disk space while writing the instrumented executable. If it happens anywhere but in writing the symbol table, the error is handled normally; if it happens during the writing of the symbol table, Execution View shows an error message coming from libmld, and the MainView remains with an hourglass cursor. Workaround: Kill the debugger, free up sufficient space on the disk, and start the run again. o During data collection, the collector, cvmon, might run out of disk space. In this case, it posts an error pop-up to the effect of ``bead write failed: no space left on device''. Workaround: Kill the debugger, free up sufficient space on the disk, and start the run again. o The Performance Analyzer does not support COFF executables. o cvmeter occasionally core dumps. We have been unable to reproduce the problem. (Incident# 185150) Workaround: restart cvmeter. o cvperf can grow enormously on experiment switch, and it has been found to occasionally core dump while switching as well. (Incident# 122213) Workaround: take down cvperf and bring up a new one. - 23 - o The Performance tools can collect a great deal of data, and easily fill a disk. For typical programs, basic- block sampling can collect between 0.25 and 2 Mbytes of data at each sample point. PC sampling data can amount to between 0.25 and 6 Mbytes for each sample. Workaround: Use care in specifying how many samples you take to avoid this problem. Be especially careful in using Pollpoint sampling; it should normally be used collecting only callstacks, not function counts, basic-block counts, or PC sampling data. Sampling is not expensive in tracing experiments. o The Main View has a notion of a default trap that is a stop trap if data collection has not been enabled in the Performance Panel (where ``enabled'' means after Accept or OK was clicked), and a sample trap if it has been enabled. This setting is independent of the default trap set in the Trap Manager. Clicking in the margin of the MainView source window sets or clears the MainView default trap, and does not affect a trap of the other type. o malloc/free traces can be quite voluminous and difficult to process in Heap View. When doing malloc/free tracing, be careful to design your experiments to exercise only those regions of your code that are problematic, and minimize the amount of trace data collected. It is difficult to estimate the volume of data produced. Each event writes 20 to 80 bytes, or more, depending on the depth of the callstack at the time of the call. A 10-minute experiment with the WorkShop Performance Analyzer wrote 140 Mbytes of trace data. Reading this experiment took ~12 minutes on a 256-MB Onyx machine. o The WorkShop Performance Analyzer can record experiments on MP FORTRAN programs, but there are a number of anomalies in the displayed data that require explanation. For all FORTRAN MP compilations, parallel loops within the program are represented as subroutines with names relating to the source routine in which they are embedded. The naming conventions for these subroutines are different for 32-bit and 64-bit compilations For example, in the linpack benchmark, most of the time spent is in the routine DAXPY, which can be parallelized. In a 64-bit MP version, the routine has the name "DAXPY", but most of that work is done in the MP routine named "DAXPY.PREGION1". In a 32-bit - 24 - version, the DAXPY routine is named "daxpy_", and the MP routine "_daxpy_519_aaab_". In both cases, for an ideal time experiment on a uniprocessor -g run, the inclusive and exclusive function level times are correct. The source annotations, however, behave differently and incorrectly in most cases. In 64-bit source annotations, the exclusive time is correctly shown for each line, but the inclusive time for the first line of the loop (do statement) includes the time spent in the loop body. This same time appears on the lines comprising the loop's body, in effect, representing a double-counting. When used in conjuction with WorkShop Pro MPF's Parallel Analyzer View, the loop performance data will incorrectly also reflect the double counting, and the time will not be always shown as a percentage: whenever it would exceed 100%, it is shown as . The numerical time value shown reflects the double counting. In 32-bit source annotations, the exclusive time is incorrectly shown for the line comprising the loop's body, as the line-level data for the loop-body routine ("_daxpy_519_aaab_") does not refer to proper lines. If the program was compiled with the -mp_keep flag, the line-level data should refer to the temporary files that are saved from the compilation, but the temporary files do not contain that information, so no source or disassembly data can be shown. The disassembly data for the main routine does not show the times for the loop-body. If the 32-bit program was compiled without -mp_keep, the line-level data for the loop-body routine is incorrect, with most lines referred to line 0 of the file, and the rest to other lines at seemingly random places in the file. Consequently, spurious annotations will appear on these other lines. Disassembly correctly shows the instructions, and their data, but the line numbers shown are wrong. MPF's Parallel Analyzer correctly shows the loop data in most cases, but the same incorrect line numbers can cause data relating to one loop to show up in other parts of the program. This reflects what is essentially the same double-counting problem as seen in 64-bits, but the extra counts go to other places in the file, rather than the first line of the loop. - 25 - NOTE: We recommend against using the -mp_keep flag. o For MP experiments, switching between threads will cause the calipers to change to points valid for the new thread. Switching back may use different points, and therefore, show different numbers. Set the calipers manually after switching to ensure proper placement. o For MP experiments, stopping one thread can cause the notion of time in other threads to get confused. It is not recommended. o The inclusive data shown in cvperf represents the instruction counts and/or PC sampling data summed over the routine and those routines that it calls. The computations are based on a heuristic that assumes that all calls from all callers are equivalent. For programs where this heuristic is not applicable, for example, where one call to a matrix-multiply routine is for matrices of order four, while a second call is for matrices of order 100, the cumulative data may be misleading. o Line-level data assigns a value to a line equal to the highest value for any instructions attributed to that line. It can be confusing, because compiler optimizations often rearrange the code in ways that is non-obvious. Looking at a disassembly view of the data can help. o Line-level data from assembler routines can be misleading. The symbol table often has instructions attributed to the wrong source line. o In some cases, line number data for a C++ routine that uses inline virtual functions defined in an included file gets the line numbers incorrectly displayed as if they came from the file in whinch the defining file is included. This causes incorrect line-level data to show at the lines in the original file. The Disassembly View in cvperf shows performance data for each instruction, and may help disambiguate attribution. o cvperf filters out nodes and arcs that were not executed during the current caliper setting. This feature can lead to confusing displays, where nodes that are known to be in the program do not appear. Workaround: The Preferences menu can be used to disable the filtering. - 26 - o cvperf does not support live performance experiments. That is, you should not bring up cvperf until the experiment is over. If you do, it will not update as more data is recorded. o The source annotations from cvperf use an annotated scrollbar that has colored tickmarks corresponding to those lines whose performance data is greater than the threshold set by the Data Highlights menu. Since the same line may be above the threshold in more than one data value, the colored tickmarks obscure each other. Workaround: Set the threshold (using the Data Highlights dialog from the Display menu) to all but one of the data items to 100%, and only the tickmarks corresponding to the non-100% variable will be shown. o Performance experiments on multi-process applications can occasionally be unreliable if sample events are quickly preceded by process creation, or succeeded by process termination. o Heap View scrolls poorly and blocks flash on large experiments. Its functionality has been mostly subsumed by Leak View, Malloc View, and Malloc Error View. (Incident# 67628) o The target process is shown as stopped during some system calls. It will be resumed by the system, and continuing it manually will cause the experiment to be corrupted. Workaround: Do not continue a process stopped at any trap you did not set yourself. o Callstacks may be wrong in MP experiments. (Incident# 189826) o If you are running a performance experiment which requires instrumentation (an example would be "Get Ideal Time per function & source line"), cvd may abort. A core file from cvpcs will be left in /usr/tmp. The abort will occur if the target program stops within the last function defined in the executable. (Incident# 195108) Workaround: Find the last function and insert another dummy function which is never called and then rebuild. The user can find the last file and function of the executable by running dis(1) and examining the tail of the output. - 27 - o Pollpoint sampling will fail if the target process forks, and the parent exits before the child. (Incident #186429) 5.5 WorkShop_Tester 5.5.1 WorkShop_Tester_Limitations o Instrumented programs can increase in size by a factor of 2X to 5X. However, DSO caching and sharing alleviates this problem greatly. o Block and branch coverage are at the assembly language level. They can provide useful metrics and do map back to the source lines. Note that several assembly branch instructions may map back to the same source line. To see the C, C++, and Fortran source level blocks and branches, use cvcov lssource. o Compilation with the debug flag "-g" builds assembly language branches and blocks that can never be executed. This adversely affects overall coverage. By compiling with "O1" (the default), some of the unused assembly branches and blocks are not built. This gives a more accurate block and branch coverage metric. Function and arc coverage are unaffected by compile flags. o C++ in-line functions are not counted as functions unless they are out-of-lined by the compiler. o By default, arguments of functions are not displayed in query results. This can be confusing for C++ overloaded functions because there is no way to distinguish between them. To work around this problem, use the -arg option to show full function signatures. o The default size of the SourceView annotation canvas may not be large enough to hold very large counts. The resource name for setting canvas width for SourceView is "canvasWidth". The default value is 60. The user can modify this width by modifying the following resource found in the Cvxcov app-defaults file, "Cvxcov*test*testData*canvasWidth". o Tester currently uses object level instrumentation. This has several advantages: (1) Coverage data can be obtained without access to the source code. (2) Coverage data can be obtained without recompilation/rebuild. - 28 - (3) This supports C, C++, and Fortran without special language support from the compilers. This has several disadvantages: (1) Block and branch counts are at the assembly language level. (2) More detailed coverage requires knowledge of the language semantics. For example, has every possible case in a multiple conditional fired during testing. o Weak externals refer to an aliasing facility used by the compilation environment. For example, while user programs may call the function "read", the actual function name in the C library that implements "read" is "_read". In this case, "read" is a weak external for "_read". If the user CONSTRAINS coverage on either name, Tester will report the results correctly. However, Tester will choose the name used to implement the function, in this case "_read". o -func_pattern is a function pattern used in the following cvcov subcommands: lsblock, lsbranch, lsfun, lstrace. Currently, only the following "patterns" are matched. "DSO:*" -- all functions in a DSO DSO:function_name -- specific function in a DSO function_name -- function_name in main program and dso's < option not used > -- all functions are included in query o Sharing of the WorkShop Performance Analyzer performance experiment data is not supported in this release. In the future, we will allow the user to run a cvperf experiment and then use cvcov mktest to link to that experiment data. o Output of query results to a printer is not supported in this release. As a workaround, the user can save query results to a file, and then send that file to a printer. o Experiment data for test sets/test groups cannot be moved/copied (mv, cp) without invalidating the data. Leaf tests can be moved/copied. o Both the lstrace feature (argument tracing) and the lssource feature (mapping block counts to actual source) require the code to be compiled with -g. A notable exception to this is return value tracing which can trace the return value on functions that are not compiled with "-g" (e.g., libc functions). - 29 - o cvcov requires that all instrumentation be performed before the experiment is run. This includes instrumentation for programs that are forked/exec'ed or sproc'ed. cvmon is the program used by cvcov to monitor the experiment. If cvmon encounters child processes, and the coverage experiment includes any executables other than the main program, then cvmon will instrument the executables for the child processes "on the fly". cvcov will not process coverage for these "on the fly" instrumented executables, because cvmon has not used the correct coverage instrumentation criteria. This can cause performance and space overhead. o IRIX 5.1 and later binaries are supported (no support for IRIX 4.0.X binaries). Also, binaries built with the "non_shared" flag are not supported for instrumentation. o Instrumentation criteria "counts" must at least include "-bbcounts". For example, if user want to test function pointers the instrumentation file must contain the following line, COUNTS -bbcounts -fpcounts o The current model for running instrumented programs requires that a separate process (cvmon) monitor the programs that are undergoing coverage analysis. This requires existing test scripts to be modified in the following manner: old script: # program arg1 arg2 new script: # cvcov mktest -cmd "program arg1 arg2" -testname test # cvcov runtest test o There is potentially a large amount of data that can be captured when running multiple tests for large programs. There are several options to the "runtest" command that help manage this data. The "-noarc" option is used to eliminate the capture of arc data in the experiment result (e.g., arc AB is equivalent to function A calls function B from line X). This significantly reduces the amount of overall count information for the test coverage result. The -rmsub option is used to retain the overall results for the top level test set or test group, not for the - 30 - individual subtests. There are several interactions of the -rmsub and -sum options worth noting. If the -rmsub option is used, a subsequent "runtest" using the -sum option will not accumulate the counts data for these two runs. In this case only the second run will be in the top level test set/test group. The -sum option will sum up data only according to the count data that is in all the subtests currently and does not use the information in the top level test set or test group. When using the -sum and -rmsub options together, the count data will be accumulated and the subtest data will be deleted. o Source highlighting for statement that cover multiple lines only highlights the last line. This is due to a limitation in symbol table data generated by the compiler. For example, in the following source statement only the second line will be highlighted: printf("This is a test for %s at %d", 0 testname,whichDrive); o If the DSO cache directory has been removed, all the existing experiments may be invalid and Tester may not work. 5.5.2 WorkShop_Tester_Bugs o Programs that use argv[0] to build hardcoded filenames get confused by the renamed instrumented program (e.g., becomes ). o An instrumentation bug can cause the instrumented program to core dump if it calls the function "_BSDsetjmp". As a workaround, if you are instrumenting "libc.so.1" for counting, you should include the following line in your instrumentation file: EXCLUDE libc.so.1:_BSDsetjmp o Unlike any of the other tools, only the first of a number of sequential highlight lines will be marked on the Source View scroll bar. This was done for performance reasons. - 31 - 5.6 WorkShop_Environment o If the colors of your WorkShop windows look too dark to read or conversely if they look completely washed out, there may be a discrepancy between the gamma value you are using and the value your X server is using. The default value of gamma on installation is 1.7 but users running X programs may prefer a value of 1.0. Workaround: If you change your gamma value, by running the gamma program (installed with eoe2.sw.gltools), restart your X server. o The network license mechanism used by WorkShop performs periodic checks to ensure that a license is available. Once obtained, a license is valid for 20 minutes. The license is validated every 10 minutes, and renewed for an additional 20 minutes if all is well. This process requires that WorkShop be actively running to be able to perform these checks. If the tool is unable to check the license server for 20 minutes, the license is lost, and the tool must be restarted to get a new license. Therefore, suspending a WorkShop process (using , for example) for more than a few minutes loses the tool's license. o The WorkShop environment works with one configuration management system at a time. This affects all users running WorkShop on that machine. o The Online Help system covers most of the product at a large granularity. For example, the description of a particular button may be grouped with the other buttons in its area rather than having its own help card. This is by design. There are sporadic problems with the context-sensitive help feature. When you click on a widget, you may get the wrong topic or an invalid help card message. If this occurs, bring up the help for the particular window, display the Help Browser, and look for the widget in the subtopics under the window topic. o Due to a Motif bug, the key does not always bring up a help card for selections in menus or for other disabled items. Workaround: Use the context-sensitive help in the help menu or select the relevant help topic from the Help Browser. - 32 - o The default for string data is to display it as a hex address. If you prefer the behavior of showing a string for char *, you can set *autoStringFormat to True in your .Xdefaults. This will automatically change the result format from the default to string for char * and char expressions in the ExpressionView, VarBrowser, and DataBrowser. o Customers displaying to non-SGI X displays and having difficulties with ExecutionView startup (a busy cursor that never goes away) should try switching *executionView*TerminalCommand in /usr/WorkShop/usr/lib/X11/app-defaults/Cvmain from the xwsh version to the commented out xterm version. - 1 - 6. Documentation_Errors The manuals included with the WorkShop option are CASEVision/WorkShop User's Guide, and CASEVision Environment Guide. Throughout the CASEVision/WorkShop User's Guide, cvstatic filesets are described as consisting of lines specifying either file names or include paths. Every fileset file must begin with a single line saying -cvstatic. Even if the fileset was created by the compiler front-ends in response to the -sa flag, it might not begin correctly. The front-ends do not automatically start the fileset with the -cvstatic line. You will need to edit the fileset yourself to make sure that -cvstatic appears as the first line. In Chapter 1, "Using the Build Manager," pages 17, 19, and 20 make reference to the Operation menu for performing configuration management. This menu no longer exists. Configuration management can be performed from the "Versioning" submenu in the Source menu in Main View or from the "Versioning" submenu in the File menu in Source View. In Chapter 4 of the CASEVision/WorkShop User's Guide, ``Static Analyzer: Creating a Fileset and Generating a Database'', the section ``Using Command-Line Options to Create and Use a Fileset'' refers to the flag -mode BOTH. This flag is no longer needed. The ``List Unused Variables'' query referred to in Chapter 5 of the CASEVision/WorkShop User's Guide, does not exist. cvstatic's ``List Unused Functions'' lists non-member functions only; unused member functions are not included in the results. The Variable queries ``Where Allocated'' and ``Where Deallocated'' do not exist. Chapter 5 of the CASEVision/WorkShop User's Guide incorrectly states the meaning of the cvstatic query ``Where Type Used''. This query should list where a typename is used, other than in declarations and definitions of functions and data. It lists the use of a type name in cast expressions and in other type definitons. However, the query does not work at all on C programs. Chapter 4 of the CASEVision/WorkShop User's Guide describes how to use the -sa compiler option to build a cvstatic parser-mode database. There are two limitations on using this -sa option: - 2 - o In Fortran, you can't specify an alternate directory where the database should be built. In C and C++, you can specify -sa, , but f77 accepts only -sa and always builds the database in the current working directory. o You cannot use both the -sa flag and the -MDupdate Makedepend flags in the same invocation of f77. The debugger section of the CASEVision/WorkShop User's Guide mentions that it is possible to make cvstatic queries from a debugging session in cvd. Since the manual does not describe this process in detail, there may be some confusion as to what actually occurs. Using the Query menu is a lot more involved than a simple search. These queries invoke the Static Analyzer and require that a cvstatic database be built if none currently exists. If you have extensive queries to make, we recommend going to the Static Analyzer directly. When you select a query from the Query menu in cvd: o If there is no cvstatic.fileset file or database in the current directory (that is, the directory from which cvd was started), cvstatic extracts the names of the files from the executable being debugged and uses them to build a fileset. cvstatic analyzes them in scanner mode and then processes the query requested from cvd. The Query menu in cvd is greyed out while this analysis takes place. o If there is exactly one answer to the query, cvd will scroll its Source View to the appropriate file and highlight the appropriate line. o If there is more than one answer, cvstatic cannot tell which definition corresponds to the particular occurrence of the name you were asking about, and so it pops up a dialog telling you to consult the cvstatic (currently iconified) for information about the definiton sites. o If there is no answer to the query (which may happen if the scanner mode misses a valid definition site, or if the executable is missing the path names of some files), cvd will not change the location curretly displayed in its Source View. No dialog box pops up to notify you of the lack of results. - 3 - o If, however, there already is a cvstatic database in the current directory, the behavior of the query can be more confusing. cvstatic consults the existing database to process the query and returns a result. If, however, the database does not correspond to the program you are debugging, this may mean that cvd will load and scroll to a file that is not in your executable. The following commands are available on the Debugger command line but have not yet been documented: alias alias [name1 ["name2" | name2]] - Lists all aliases or with arguments define a new alias. unalias unalias name assign assign expression1 = expression2 - Assigns specified expression to specified program variable. attach attach pid - Attaches to specified process ID. detach detach - Detaches the current process. dump dump - Prints variable information. goto goto line - Goes to the specified line number. memory / - Prints the contents of the specified address, for count bytes in the specified format. The formats are: o d prints a short word in decimal D prints a long word in decimal o prints a short word in octal O prints a long word in octal x prints a short word in hexadecimal X prints a long word in hexadecimal b prints a byte in octal c prints a byte as a character s prints a string of characters that ends in a null byte f prints a single-precision real number g prints a double-precision real number printregs printregs - Prints the contents of the registers. sh sh [ ] - Calls a shell or execute a shell command. source source - Executes commands from the specified file. - 4 - The expression command documented on p. 148 is incorrect. It is a variable, not a literal. It has these two forms: o / [count] [format] , [count] / [format] On p. 318 in Chapter 19, "Performance Analyzer Tutorial," the first step in the tutorial setup directs you to the /usr/demos/WorkShop/performance/tutorial directory, which is incorrect. The correct directory is /usr/demos/WorkShop/performance. The WorkShop Performance Analyzer documentation is incorrect in describing Heap View, as follows: o Heap View has been changed to show a count of malloc/free/etc., errors on the status line, and the "Unmatched Frees" button has been changed to read "Malloc Errors", as it now shows other errors in addition to duplicate and erroneous free calls. Appendix B, "Customizing WorkShop Tools," shows the resource buildCommand on p. 550 as applying to the Build Analyzer. It actually applies to Build View. This appendix left out the *runBuild resource, which also applies to Build View. If true (the default), cvmake begins its build immediately upon launch. - 1 - 7. Licensing_WorkShop_with_NetLS Your copy of WorkShop 2.3 requires a software license in order to operate. This chapter defines some important software licensing terms, describes the basic procedure for obtaining, installing, and testing a software license for WorkShop 2.3, and lists addresses and phone numbers that you can use to contact Silicon Graphics License Administration. For more information about software licenses, see the Network License System Administration Guide, which provides detailed information on obtaining, installing, using, and administering software licenses. It is included in the system software documentation; the online version is in the subsystem netls_eoe.books.NetLS. 7.1 A_Few_Definitions A software license is a collection of information that, after installation, allows you to use a licensed software product on one or more systems. The software license information includes the license type, the license expiration date, a license password, and system identification numbers (sysinfo and serial numbers). You can get a system's sysinfo number by giving the command /etc/sysinfo -s. The license must be installed on the system that has the sysinfo number included in the software license information. If the sysinfo is ``Any,'' the software license can be installed on any system. There are two types of software licenses, node-locked and concurrent, and two durations of software licenses, temporary and permanent: node-locked A node-locked license is installed on a particular system (node) and allows the licensed software to run on that system. concurrent A concurrent license allows the licensed software to run on one or more systems in the network simultaneously. The number of systems (nodes) allowed is included in the software license information. The system on which a concurrent license is installed must be configured as a Network License Server. Any system on the same network must be configured as a Global Location Broker. (See the Network License System Administration Guide for more information about Network License Servers and Global Location Brokers.) - 2 - temporary A temporary license allows you to use the licensed software for a short period, typically a week to several months. The expiration date tells you the last date on which you can use the licensed software. Temporary licenses are often shipped with software so that you can use the software before a permanent license is issued. permanent A permanent license allows you to use this release of the licensed software for a very long time. For example, an expiration date in the year 2038 indicates a permanent license. Permanent licenses are issued only for software that has been purchased. 7.2 Obtaining_and_Installing_a_Software_License This section explains the procedure for obtaining and installing a software license: checking to see if you have received software license information, determining if you need to install a license, requesting software license information if you need it, identifying the system on which you will install the license, installing the software license information, and verifying that the license is working. 1. Check to see if you have received software license information. Software license information is distributed in several ways: on labels attached to a Software License Registration card, on sheets of paper included with the product, or by mail, FAX, or electronic mail. 2. Determine if you need to install a software license. You may or may not need to install a software license for WorkShop 2.3: o If you are updating to this release of WorkShop from an older release, you need to obtain and install a new license. o If you have received both a temporary license and a permanent software license, install the permanent license; do not install the temporary license. o If you have received a permanent license, you should install it because it enables you to use - 3 - the software that you have purchased. o If concurrent licenses are used at your site and you plan to use an already-installed license, you can install and use the licensed software on your system without installing a license. o If you have received a temporary software license and do not need to use the software immediately, you may choose to wait to install a license until you obtain the permanent license. 3. Request a software license if you don't have a software license at all, or if you have a temporary license and need a permanent license. To obtain a software license, fill out the Software License Registration card that was included with the software (or the replica in the Network License System Administration Guide). Send the information or the card by electronic mail (preferred), FAX, or mail to Silicon Graphics License Administration or your local service provider (see the next section for addresses). After your request is received by Silicon Graphics or your local service provider, you should receive a software license within two business days. 4. Identify the system on which you will install the software license. Because software license information usually must be installed on a particular system, follow these guidelines: o If the sysinfo is a number, identify the system that returns that number as the output of the command /etc/sysinfo -s. (It may be easier to identify the system using the serial number, which is included in the software license information.) o If the sysinfo is ``Any,'' you can install the license on any system you choose. o If the sysinfo number included with the software license information doesn't match the sysinfo number of the system on which you want to install the license, contact Silicon Graphics License Administration. - 4 - 5. Install the software license (temporary or permanent). Check the ``license type'' listed in the software license information to find out whether the license is a node-locked license or a concurrent license. The installation procedure depends on the license type: o If it is a node-locked license, see Chapter 3, ``Installing Node-locked Licenses,'' in the Network License System Administration Guide for instructions on installing the license. o If the license is a concurrent license, you may need to configure the system on which you plan to install the license as a Network License Server. If there is no Global Location Broker on your network, you must set up a system as a Global Location Broker, too. See Chapter 4, ``Setting Up Global Location Brokers and Network License Servers,'' of the Network License System Administration Guide for instructions. After the Network License Server and Global Location Broker are set up, follow the instructions in Chapter 5, ``Installing Concurrent Licenses,'' of the same guide to install the license on the Network License Server. 6. Verify that the software license has been successfully installed. To verify that the software license is working, try running one of the licensed programs in WorkShop. The licensed programs are: cvd(1) and cvstatic(1). If you installed a temporary license and you are entitled to a permanent license, replace the temporary license with a permanent license as soon as possible to ensure uninterrupted use of WorkShop. 7.3 Contacting_Silicon_Graphics_License_Administration In the United States and Canada, Silicon Graphics License Administration provides software license information to Silicon Graphics customers. You can contact Silicon Graphics License Administration in these ways: Electronic mail: license@sgi.com FAX: (415) 390-0537 - 5 - Mail: Software Licensing M/S 134 Silicon Graphics, Inc. P.O. Box 7311 Mountain View, CA 94039-9600 In an emergency, you can telephone Silicon Graphics at (800) 800-4744. If you are not in the United States or Canada, or if you purchased the system or software from a vendor other than Silicon Graphics, please contact your local service provider.