Date: 17 March 1983 10:58 am PST (Thursday) From: Birrell.pa Subject: DebugTool and CoCedar This message is addressed mainly to those who haven't yet converted from CoPilot to CoCedar. If you've already converted, skip the first section, but look at the rest of the message. This isn't really documentation, but hopefully it will be enough to enable people to use CoCedar. We hope that after the 4.0 release, nobody will be using CoPilot. ----------------------- Converting from CoPilot. To be able to use CoCedar, you must be running the current version of 4.0 as your client world, and you must have a debugger volume whose size is at least 28000 pages. The Othello command files now on [Indigo]<Cedar>Top> organize your disk in a suitable way. To install CoCedar on your debugger volume, use Othello to erase your debugger volume, then install BasicCedarDorado.boot there. Use Othello's "Set Physical" command to set the physical volume boot file from your client volume. Now boot your debugger volume. CoCedar will start up, initialize itself, outload itself (920 in the maintenance panel), and boot your physical volume, which should cause your client volume to start up. Once your client volume has initialized, you should make a checkpoint, and you may want to use Othello again to change your physical volume boot file. This slightly tortuous sequence is needed because erasing the debugger volume invalidates any existing client checkpoint. ----------------------- New Versions. Normally, you can install a new version of CoCedar just by booting your debugger volume (with the "L" switch if necessary to provoke an automatic bringover). ----------------------- Action areas. When your client world invokes the world-swap debugger, things proceed pretty much as with CoPilot (i.e. a long time with 920 on the screen). When you get to the debugger, an action area should appear (eventually - be patient!); in the fine print of the action area you will see that it says "World=Outload" to indicate that the action is associated with an outloaded client world. Expressions typed to such an action area are interpreted by looking in the outloaded client's virtual memory, and if you use the "Set" and "Clear" menu commands of that action area, you're talking about breakpoints in the outloaded client. Rememember that you can also get actions from the debugger world if the debugger breaks, and that the vanilla user executive is associated with the debugger, not the outloaded client. Proceeding from the most recent action causes a world-swap back to the client. ----------------------- The DebugTool. This tool appears automatically in the debugger. It provides some global control over the debugging facilities, and allows you to poke about amongst the client's processes. The top line of the DebugTool's menu allows you to select what client is being debugged; consult the full DebugTool documentation (soon to be in preparation) before using this menu. At the bottom right corner of the menu are the "Screen" and "Kill" commands. Their effect is identical to CoPilot's "UserScreen" and "Kill Session" commands. At the bottom left are "List LoadState" and "List Context". "List LoadState" enumerates the currently loaded configurations in the client. If you type the name of a configuration as the text beside the "Context" button, then click "List Context", it will enumerate the modules in that configuration. The DebugTool is also available in your ordinary Cedar world. Just give the command "DebugTool" to the userExec. You can then use the DebugTool to examine parallel processes without resorting to the world-swap debugger. This is much more convenient, provided the areas you are debugging are not critical to the operation of Cedar itself. ----------------------- Processes. The process facilities are based on the concept of "freezing" a process at some point on its call stack. This means that the process continues execution normally, but when it returns to that point on its call stack, the process will stop executing until it is thawed. Of course, there is the special case where you freeze the process at its current frame, so it stops executing immediately. The DebugTool allows you to freeze and thaw processes, and to look at the frozen frames of processes (even while the rest of the process is still executing). There is no way to look at a process (or part of a process) that isn't frozen. There are four "Freeze" buttons: "All", which freezes all processes at their current frame; "Ready", which freezes all ready processes at their current frame (i.e. processes that aren't suspended for a monitor lock, condition variable wait or fault); "PSBI" which freezes the process whose number (PSB index) is given as the text beside the "PSBI" button on the right of the viewer. Finally, the "Freeze Context" button will freeze all processes associated with a perticular configuration or module, freezing them at the boundary of the context. More precisely, "Freeze Context" enumerates all processes, and determines every process that has somewhere on its call stack a frame within the specified module or configuration; each such process is frozen at the point where control would return to within the module or configuration; any process currently executing (or waiting or faulted) within the module or configuration stops executing immediately. ----------------------- Examining frozen processes. For each process that is frozen, the DebugTool displays three buttons, labelled with "Adjust", "Thaw", and a description of the process's current state. The state says things like "ready" or "waitingCV" or "pageFault", followed by the name of the frame at which the process is frozen. There is no way to look at non-frozen frames of the process. The "ready", "waitingCV", etc. are wrapped in parentheses if the process's current frame is not frozen (i.e. if the process is still executing). If you click the left mouse button on the process-state button, DebugTool gives a brief summary of the process's call stack (from the point at which it is frozen). If you click the right mouse button there, DebugTool will create an action area for that process, which allows you to look at the frozen parts of the call-stack in more detail. The "Thaw" button associated with a frozen process will un-freeze the entire process. The "Adjust" button will change the point at which the process's call-stack is frozen to be the boundary of the module or configuration speciified in the text for "Context" at the right of the viewer. You can't thaw or adjust a process while it has an action area - proceed the action area first. When you're using the DebugTool in CoCedar, you will often want to look at the entirety of a process, rather than just the part inside a particular context. To do this, use "Freeze Context" to freeze the appropriate processes, then set the context string to empty (by clicking its label with the right mouse button), then click "Adjust" for the process of interest. This causes the entire process to be frozen. Beware: if you're using the DebugTool in your normal Cedar world, freezing the entirety of a process is often wrong: you may freeze it while it is inside some criticial system monitor lock. ----------------------- They're really frozen! If you resume the outloaded client (for example, by proceeding the action that invoked the world-swap debugger) while some processes are frozen, they really are frozen when the client resumes. This can be important when debugging parallel computations, but it can be dangerous. In particular, beware of resuming the client while critical system processes are frozen! The "screen" button is included in this warning, because it resumes the debugger to show you the screen. There is one particular bug in the present version of AMProcess: if you resume the debugger while the debuggee's current process is frozen, the debugger is likely to get an address fault sometime later. ----------------------- Style. You will find the DebugTool more pleasant if you use the full power of its process enumeration facilities. You should very rarely need to use "Freeze All". Almost always, you know what set of modules or configurations you're debugging; if you freeze just the processes associated with them, DebugTool will do the filtering for you and you won't have so much trouble deciding what process to look at. ----------------------- Performance. Some of the CoCedar facilities are very slow when looking at the outloaded client. Be patient. I find it useful to keep Watch running in my debugger, just so I can be sure it's still making progress. ----------------------- Bugs. There are still several bugs. PLEASE let an implementor know if something doesn't work. If CoCedar breaks, however, you still have a chance to look at your outloaded client. If CoCedar has been invoked by a client and you haven't resumed the client at all (e.g. UserScreen), you can restart the debugger without losing the client outload by booting your debugger volume with the "W" switch set. (CoCedar does this automatically in the situation where CoPilot says "inloaded twice, click to boot"). Alternatively, you can reinstall CoCedar by booting your debugger volume with no switches, in which case after outloading itself the debugger will boot your physical volume. ----------------------- Symbol tables. Just like Cedar, CoCedar often manages to find the correct symbol table automatically using the version maps. However, this is unlikely to be true for the modules you're debugging. CoCedar will not automatically look at files on the client volume - you'll need to fetch them explicitly onto the debugger volume using BringOver, or the ClientFileTool. ----------------------- Andrew