From: Jason Self Date: Sun, 18 Jun 2017 05:10:29 +0000 (-0700) Subject: Adding section 4 X-Git-Url: https://jxself.org/git/?a=commitdiff_plain;h=7c18e64acffa097aa2f56d837e7da66b20dd5645;p=mudman.git Adding section 4 --- diff --git a/md/debugging.md b/md/debugging.md index a4dc184..7837184 100644 --- a/md/debugging.md +++ b/md/debugging.md @@ -775,6 +775,317 @@ application program, that are not directly seen in the MSTACK representation but are made visible by various other features of MEND. These will be discussed where appropriate in later sections. +IV Issuing Commands to MEND +=========================== + +IV.1 Types of Commands +---------------------- + +There is a need in debugging systems similar to MEND for two types of +commands for controlling operation. One type is a set of short, +immediate-action commands that the user of the debugging system may +issue at any time, such as a command to completely stop all activities +of the debugging system and to exit. The other type is the set of all +commands not belonging to the first set. This includes commands that +take arguments and those that can only be given while the application +program is suspended from execution. + +IV.2 Immediate Interrupt-Level Commands +--------------------------------------- + +In MEND's normal mode, various actions occur automatically. Most +importantly, the application program is executing and the displayed +representation of the MSTACK is being updated correspondingly. During +this time the programmer may type ahead to the application program, +but, since there is only one physical cursor that is used by both +MEND's display and typein echoing that must therefore jump back and +forth between the two text entry positions, a large amount of typein +is awkward. Therefore, all immediate action commands that the user can +issue while MEND is in automatic mode are single characters. To +minimize the chance of conflict with typein that the executing +application program might read, MEND immediate action commands are +invoked by typing certain ASCII control characters. Furthermore typing +one of these control characters causes an interrupt to occur which is +handled by MEND and allows immediate response. + +Note that this arrangement requires that there be certain reserved +characters, as listed below, that cannot be used to communicate with +the application program. Normally this presents no difficulty. An +alternative method was considered that required the reservation of +only one control character. However, the user would be required to +type an additional character as an argument signifying what function +is intended. There did not seem to be a great advantage to this scheme +and it was considered after the first scheme had been implemented. For +this and other reasons stated later in this section, the alternative +scheme was discarded. + +From the user's viewpoint, the currently implemented interrupt-level +commands are as follows. (ASCII control characters are represented by +"↑" followed by the corresponding letter.) + + ---- ------------------------------------------------ + ↑L clear screen, reprint stack and input + ↑Q Quit from current MEND + ↑E End automatic mode + ↑B Begin automatic mode + ↑U Unprint (stop displaying stack) + ↑P Print (start displaying stack) + ↑O skip Over (completely evaluate) current object + ↑N Next step (used when not in automatic mode) + ---- ------------------------------------------------ + +The command invoked by typing ↑L is for housekeeping purposes. It +causes extraneous information (e.g., old program output) to be cleared +from the screen and all MEND-related constantly-displayed information +to be reprinted. Unread input is also reprinted. + +The command invoked by typing ↑Q is used to exit from an invocation of +MEND. It has the effect of stopping all actions related to monitoring +the application program and allowing the program to continue normally. +In this way a programmer may discard MEND and continue running the +application program without the need for restarting it at the +beginning. + +The two commands invoked by typing ↑E and ↑B switch MEND between +automatic mode, the only one described thus far, and non-automatic +(command) mode. Command mode will be described in the next section. + +Sometimes it is desirable for the sake of saving both computer time +and the application programmer's time to turn off printing of the +MSTACK. MEND will continue to monitor program execution and store the +appropriate information but it does not display it. Nor does it pause +between steps in the normal manner. This is mainly useful when +breakpoints are present to turn on printing or switch to command mode. +At that time MEND will know how it got to the current level and will +be able to display the MSTACK as usual. Two commands invoked by typing +↑U and ↑P toggle the state of printing. + +Whenever the programmer is satisfied that a particular call of a +function is working properly or for some reason he or she is not +interested in seeing the details of evaluation of some object, typing +↑O just before the object's evaluation invokes a command that causes +MEND to skip over that evaluation and continue normal monitoring and +display immediately after a value is returned. Unlike turning off the +printing, no monitoring is performed here at all so the evaluation +proceeds as fast as it would without MEND. This is actually handled by +causing Muddle to leave single-stepping mode during the evaluation of +the object. + +The last command, invoked by typing ↑N, is special in that it is +ignored in automatic mode. Its actions in command mode will be +described in the next section. It is an interrupt-level command mainly +for convenience and compatibility with DEBUGR. + +Bruce Daniels' DEBUGR is the prototype Muddle multiprocessing +debugging system. It provides a simple user interface to Muddle's +single-stepping functions that makes single-stepping through a Muddle +program appear similar to single-stepping through an assembly-language +program with DDT[^18][^19]. The choices of characters for invoking +many of the MEND functions were based upon the characters used to +invoke similar functions in DEBUGR. Many of DEBUGR's command +invocation characters were in turn based upon those in DDT. The object +of all of this is to build character/command associations in the +user's mind that may be carried over from one system to the next. + +Several other control-character commands are handled by MEND +invisibly. That is, the user may not be aware that they are being +handled. Most of these are commands that are already being handled by +other subsystems but must be intercepted by MEND to maintain +consistency in its environment. Two of this type, invoked by typing ↑S +and ↑G, are already set up in an initial Muddle and a third, invoked +by typing ↑F , is set up by the subsystem EDIT, which is called by +MEND as described in the next section. All three of these are used to +escape to various command levels. MEND has its own command level (see +next section) and must in many cases escape to that one instead to +maintain control. Until a method was discovered for having ITS section +the screen, it was necessary to also interrupt on carriage-returns +(↑M, the new-line character) on input to insure that typein was kept +in the proper section. + +IV.3 MEND's Command Level +------------------------- + +Sometimes the user may wish to stop the application program at some +point to examine it in more detail or to alter it or its environment +in some way. Alternatively the user may want to issue commands to MEND +that require arguments. A command level is provided for both of these +activities. + +The command level differs from the automatic mode described in the +last section in two ways. First, the application program is not +continually executing. It runs one step at a time under the direct +control of the user rather than automatically. Second, in +non-automatic mode typein is normally passed to MEND instead of the +application program, even that class of typein which does not produce +immediate action. + +When the application program is stopped, the user may either request a +service from the debugging system or examine and/or modify the program +and/or its environment. Since editing functions form a large part of +the latter class of actions, it was decided that instead of requiring +the user to "import" an editor, MEND should provide an editor by +making one available at command level. + +It is generally believed and empirical evidence indicates, that +creating a new editor is "the kiss of death" for a Muddle subsystem. A +number of Muddle editors have been tried over the years and the only +one that finally became generally accepted (and is now pre-loaded in +Muddle) is EDIT[^20] . Members of the Muddle community will tolerate +minor changes to EDIT, but they will not accept a new editing system. +The situation is analogous to one of the major obstacles blocking the +acceptance of ESP. Programmers were accustomed to using DDT to examine +and modify their machine-language programs. ESP was not compatible +with DDT and therefore did not provide the familiar interface desired. + +In view of the situation, it seemed desirable to incorporate EDIT into +the command level, essentially unaltered. EDIT uses a special reader +that either interprets input as a command to it or passes input on to +the normal Muddle reader. At first the task of superimposing a MEND +reader on top of both of these appeared difficult. After much +discussion with the current maintainer of EDIT, a very satisfactory +solution was arrived at. + +A general capability was added to EDIT allowing the specification at +runtime of a table of EDIT-like commands to be handled by +programmer-defined functions. This table is searched before EDIT's +command table and thereby provides a capability to override standard +EDIT commands. MEND basically uses an invocation of EDIT as its +command level with all MEND commands included in a table as described. +EDIT-format commands are all one or two letters and may take suffix +arguments. Currently the MEND table includes the following commands. +(FIX here means a Muddle object of type FIX, i.e., a fixed-point +number. FLOAT means a floating-point number. PPRINT[^21] is a function +that prints a Muddle object in a format which indicates the positions +of its elements and sub-elements in the tree hierarchy.) + + NAME ARG TYPE MEANING + ------ ---------- -------------------------------------------------- + ? none type out short summary of MEND commands + ?? none type out complete summary of all commands + O any Open object or MCSTACK level n (if arg n is FIX) + V none toggle Verbosity + N FIX do Next n steps (like ↑N) + OV none skip OVer current object (like ↑O) + Q none Quit EDIT & return to automatic mode (like ↑B) + QM none Quit MEND (like ↑Q) + SN FIX Set number of lines used for stack display + SV FIX Set leVel below which MEND will not 1STEP + SD number Set Delay time (FIX or FLOAT) between steps + PD FIX Pprint Displayed object in level n + PO FIX Pprint Original (actual) object in level n + AI any Add an Item to the list being monitored + DI FIX Delete Item number n from the list + PI FIX Pprint Item number n + +What the user types to the command level is inspected by EDIT. If it +looks like an EDIT command, it is looked-up in the MEND command table +or the EDIT one and handled as appropriate. Otherwise it is passed to +the Muddle reader. In general any interesting (useful) input that +Muddle should read and evaluate will not look like an EDIT command, so +there is no confusion. + +As can be seen from the table, the MEND commands include general +information retrieval ones (? and ??), system tailoring ones (V, SN, +SV, and SD), and commends that allow objects to be accessed in special +MEND locations (O, PD, PO, AI, DI, and PI. The O command is special in +that it allows an object known only by its location in the MSTACK to +be opened for examination and alteration by the normal EDIT commands. +The remaining commands duplicate control-character commands except +that they are read at normal input level rather than at interrupt +level. + +The most powerful feature of this command level is seen when Muddle +objects are evaluated. This level, and therefore the evaluation, uses +stack space below the application program and in the same process. All +bindings and pending evaluations of the program are above the command +level where they may be examined and modified at will. Most of what +constitutes MEND is in another process safely removed and hidden from +the user. Even the small amount of overhead constituting the command +level function is hidden from functions such as FRAMES[^22], which may +be used to view the levels of the application program's current +control stack. The effect is much the same as that of Muddle's +listening loop which is invoked at the current bottom of the stack in +case of error, to allow the programmer to run any program (evaluate +any object) to find and correct the problem. + +Note that for critical examination of the program, the user may +request that it be continued for a limited number of steps (usually +one) with control then being returned to him or her at the command +level. One normally would employ such a feature when the program is +executing statements near the area of suspected trouble but it is not +entirely clear how or why the program is misbehaving. + +IV.4 Breakpoints +---------------- + +Normally MEND operates in automatic mode where the application program +is running continuously. If one is aware of a particular area of +concern, one cannot and should not have to see that area as it is +reached and quickly type ↑E in order to stop the program. One may have +the program running with a very small delay time or have the printing +turned off. + +In their simplest form, MEND breakpoints stop the program when +evaluated, putting the user in command mode if she or he was not +already in it. This is the Muddle equivalent of DDT breakpoints, which +stop a program at a certain instruction. The breakpoints can also be +conditional, where the evaluation of an arbitrary object determines +whether or not to actually break at that point. + +The breakpoints as so far described are very much like the breakpoints +that can be set by EDIT. As a matter of fact, EDIT is used to set and +clear these breakpoints just as it would be in the absence of MEND. +The only real difference is that, when MEND is present, a MEND +function is called to handle the break instead of an EDIT function. + +MEND breakpoints would be useful even if they only did what was just +described. However they are more powerful. A standard EDIT-style +breakpoint is a call to the break function with a number of arguments. +The first of these is the object at which the breakpoint is set, which +will be evaluated when the user returns from the breakpoint and whose +value will be returned by the break function to the application +program. The next is the conditional object and the rest are objects +to be evaluated and printed at each break. MEND's break function +handles these as EDIT's does but also looks for a recognized ATOM +(variable name), which may come after or replace the conditional. If +such an ATOM is found, it will cause a special action to occur instead +of stopping the program: + + ------- --------------------------------------- + ON printing will be turned on (like ↑P) + OFF printing will be turned off (like ↑U) + GO free-run the object (like ↑O) + PRINT just print arguments & continue + ------- --------------------------------------- + +Other arguments will still be printed and all actions are still +predicated upon the value of the conditional. + +The first two special ATOMs (ON and OFF), perhaps coupled with manual +control, are used to allow the MSTACK to be viewed only during areas +of interest while maintaining maximum speed in other places. The next +one (GO) is used to avoid wasting time examining the details of a +functional call that is known to be working and is probably evaluated +repeatedly. When the break function returns, single-stepping resumes +as before the break. The last special ATOM (PRINT) is used to give +information at key places that might not otherwise be seen. + +One thing that was considered extremely important was to make MEND's +breakpoints compatible with those of EDIT. The problem is that a +breakpoint inserted outside of MEND might still be present when MEND +is started and vice versa. As has been stated EDIT breakpoints work +almost exactly as usual when handled by MEND's break function. The +converse is not quite true. EDITs break function will ignore the +significance of a special ATOM end simply print it as a normal +argument. Fortunately, an ATOM evaluates to itself. If it is in the +conditional position it will always be considered "true" and no harm +will be done. + +It would be easy to extend this arrangement to other special ATOMs if +other functions were considered useful. The above seem to form a basic +set in this system. At least they are useful and no one has yet +suggested another type of breakpoint that would also prove useful. + [^1]: G.A. Mann, "A Survey of Debug Systems", Honeywell Computer Journal 1973, volume 7, number 3, pages 182-198 @@ -823,17 +1134,14 @@ These will be discussed where appropriate in later sections. Technology Division Document, Laboratory for Computer Science, M.I.T., (in preparation) -[^14]: G.J. Farrell, A System for Muddle Programming, M.S. Thesis, - Department of Electrical Engineering, M.I.T., August, 1973 - -[^15]: S.W. Galley, Pre-loaded Pure MDL RSUBRs, SYS.11.28, Programming +[^14]: S.W. Galley, Pre-loaded Pure MDL RSUBRs, SYS.11.28, Programming Technology Division Document, Laboratory for Computer Science, M.I.T., November 1975 -[^16]: B. Daniels, The MDL Assembler, SYS.11.07, Programming +[^15]: B. Daniels, The MDL Assembler, SYS.11.07, Programming Technology Division Document, Laboratory for Computer Science, M.I.T., (in preparation) -[^17]: C. Reeve, The MDL Compiler, SYS.11.25, Programming Technology +[^16]: C. Reeve, The MDL Compiler, SYS.11.25, Programming Technology Division Document, Laboratory for Computer Science, M.I.T., (in preparation)