1 04/21/86  probe, pb
  2 
  3 Syntax as a command:  pb {-control_arguments}
  4 
  5 
  6 Function:  is used to examine, patch and generally debug the Multics
  7 hardcore and BCE itself, as well as providing a general memory and disk
  8 patch/dump facility.  Its requests resemble those of the Multics probe
  9 command.  It can be used at all BCE command levels.
 10 
 11 
 12 Control arguments:
 13 -bce
 14    examines bce itself.
 15 -break
 16    examines the active breakpoint.
 17 -crash
 18    examines the saved crash image.
 19 
 20 When probe is invoked at the "boot" command level, the default is to
 21 examine BCE.  When probe is invoked automatically upon encountering a
 22 breakpoint, the default is to examine the breakpoint.  Otherwise, the
 23 default is to examine the crash image.
 24 
 25 
 26 Notes:  The BCE probe command reads request lines from the bootload
 27 console.  Multiple requests may appear on one line separated by
 28 semi-colons.  The syntax of these requests varies from request to
 29 request.  The recognized requests are listed below.  Various other
 30 aspects of BCE probe are described in the following sections.
 31 
 32 
 33 List of address forms:  Several requests in BCE probe take an address
 34 describing what should be displayed, modified, etc.  These addresses
 35 can take many forms, depending on what is desired.  Valid address forms
 36 are:
 37 N
 38    specifies absolute memory location N.  N may describe any location
 39    in all of memory.  N is specified in octal.
 40 M|N
 41    specifies the virtual location N in segment M.  The interpretation
 42    of this virtual address depends on the address space being examined;
 43    refer to the dbr and proc requests.  Both N and M are specified in
 44    octal.
 45 
 46 
 47 name|N
 48    specifies the virtual location N in the hardcore segment with the
 49    specified name.  This interpretation is subject to the address space
 50    being examined.  N is specified in octal.
 51 M$entry
 52    specifies the virtual location whose address is that of the
 53    specified entry in segment M.  This interpretation is subject to the
 54    address space being examined.  M is specified in octal.
 55 M$entry+|-N
 56    specifies the virtual location offset N (plus or minus) from the
 57    address of the specified entry in segment M.  This interpretation is
 58    subject to the address space being examined.  Both M and N are
 59    specified in octal.
 60 
 61 
 62 name$entry
 63    specifies the virtual location whose address is that of the
 64    specified entry in the hardccore segment with the specified name.
 65    This interpretation is subject to the address space being examined.
 66 name$entry+|-N
 67    specifies the virtual location offset N (plus or minus) from the
 68    address of the specified entry in the hardcore segment with the
 69    specified name.  This interpretation is subject to the address space
 70    being examined.  N is specified in octal.
 71 .{+|-N}
 72    specifies the last location referenced (of any address type)
 73    optionally offset by the value N.  N is specified in octal.
 74 
 75 
 76 reg(name)
 77    specifies the named register in the crash image.  This address is
 78    not valid when examining the live BCE.  Valid registers are:
 79 
 80          prN (N = 0 to 7)
 81          xN (N = 0 to 7)
 82          a, q, e
 83          t, ralr
 84          fault, ext_fault, mode, cache
 85          dbr, bar
 86 
 87 disk(drive_name,record_num,offset)
 88    refers to a specific page of a disk drive.  The drive name is in the
 89    standard form: dska_04, or dskb_00a (subvolume device) for example.
 90    Both record_num and offset (within the page) are specified in octal.
 91 
 92 
 93 List of probe requests:
 94 before {address}, b {address}
 95    sets a breakpoint to be executed before executing the instruction at
 96    the specified address.  If no address is specified, "."  is assumed.
 97    The address must be a virtual address.  The breakpoint is added to
 98    the list of breakpoints for the segment.  Up to 120 breakpoints may
 99    be set per hardcore segment; however, all wired hardcore segments
100    share the same breakpoint area so only 120 breakpoints in total may
101    be set in wired segments.
102 continue, c
103    continues the saved image from a breakpoint.  It is the same as
104    exiting probe and entering the continue command.  Multics is
105    restarted.
106 
107 
108 dbr {value1 {value2}}
109    sets the dbr (descriptor base register) value used in the appending
110    simulation used to access virtual addresses in the Multics image.
111    If value2 is omitted, the second word of the dbr value is obtained
112    from the dbr in effect when Multics crashed.  Both value1 and value2
113    are octal values.
114 
115 
116 display address {mode {length}}
117 ds address {mode {length}}
118    displays a set of locations in a specified mode.  If length is
119    omitted, a value of 1 is assumed.  For virtual addresses, a length
120    of "*" may be specified to display to the end of the segment.  If
121    mode is omitted, octal is assumed.  Valid modes are:
122 
123          a - ASCII characters
124          d - decimal words
125          i - instruction format
126          o - octal words (default)
127          p - symbolic pointer (double words)
128 
129 
130    The locations are displayed four to a line in the desired format.
131    The value of "."  after this request finishes is the first location
132    displayed.
133 let address = value {...  value}
134 l address = value {...value}
135    modifies a series of locations starting at the address specified.
136    Each value is converted to a number of words and catenated together
137    to form the new value.  Valid values are:
138    STR
139       a quoted string of characters.  To place a quote character into
140       the string, it must be doubled.
141    N
142       a decimal number.
143 
144 
145    No
146       an octal number.
147    Nb
148       a binary number.
149    M|N
150       a pointer to segment M offset N (double word).
151    name|N
152       a pointer to the named hardcore segment offset N (double word).
153 list_requests, lr
154    lists the valid BCE probe requests.
155 mc address {-long}
156 mc address {-lg}
157    displays, in interpreted form, the SCU data found within the machine
158    conditions at the specified address.  Specifying -long also dumps
159    the machine registers from the machine conditions.
160 
161 
162 name segno
163    displays the name of the hardcore segment with segment number segno.
164 proc N
165    changes the address space used by the appending simulation for
166    displaying virtual addresses to the Nth process in the active
167    process table.  A value of 1 specifies the Initializer's process.
168 quit, q
169    exits probe.
170 reset {address}
171 r {address}
172    resets a given breakpoint; that is to say, Multics will no longer
173    break when the instruction is encountered.  The breakpoint causing
174    the return to BCE can be reset by not specifying an address.
175 
176 
177 segno name
178    displays the segment number of the named hardcore segment.
179 stack address
180 sk address
181    displays a stack trace starting at the given address.  If the word
182    offset of the address is 0, the address is assumed to refer to a
183    stack header.  Otherwise it is assumed to refer to a stack frame.
184    For each frame, the stack frame offset, entry pointer, return
185    pointer and argument pointer is displayed.
186 status {name|segno}
187 st {name|segno}
188    either lists all segments with breakpoints set in them (if no name
189    or segno is specified) or lists all offsets within a single segment
190    at which a breakpoint is set.
191 
192 
193 Notes on hardcore breakpoints:  The hardcore breakpoint facility is a
194 collection of facilities within Multics and BCE that allow probe style
195 breakpoints to be set at most BCE and hardcore instructions.  They may
196 be used largely as they are within normal Multics probe, with a few
197 cautions.
198 
199 
200 Notes on breakpoint mechanism:  The following paragraphs describe the
201 mechanism by which hardcore breakpoints are implemented.  An
202 understanding of this mechanism will prevent the user from setting a
203 breakpoint in an incorrect path; in particular, breakpoints may not be
204 set in the breakpoint handler's path.
205 
206 
207 When a hardcore breakpoint is set at an instruction, the instruction at
208 that location is relocated to the end of the segment containing it.
209 Its addressing is changed to reflect its new location.  The original
210 location is replaced with a transfer instruction to a breakpoint block
211 at the end of the segment which executes a "drl -1" instruction.  This
212 causes the breakpoint to happen.  If the breakpoint handler returns
213 without changing the breakpoint, the next instruction in the block will
214 be executed.  This is the relocated original instruction.  After this,
215 a transfer is made back to the correct place in the original program.
216 It should be noted that the instruction moved cannot be the second or
217 later words of an eis multi-word instruction.
218 
219 
220 Derail faults are handled in fim.  A "drl -1" instruction is
221 special-cased to be a breakpoint.  Fim makes a call to
222 pmut$bce_and_return to implement the call to BCE.  Any program in this
223 path cannot have a breakpoint placed within it.  In other words, a
224 breakpoint cannot be set in the path of code which gets executed
225 between a breakpoint and a return to BCE.  This path includes the
226 breakpoint handler in fim, the code in pmut$bce_and_return, any code
227 which sends and handles connects to other processors, etc.  Also, the
228 special casing of a "drl -1" to be a breakpoint only applies for
229 derails in ring 0.  Thus, breakpoints should not be set in segments
230 that will be executed in other rings.
231 
232 
233 When BCE is invoked via the toehold, it notices that a breakpoint was
234 the cause of the return to BCE and invokes BCE probe directly.  Probe
235 is free to perform a continue operation which eventually returns to
236 pmut, restarts other processors, and returns to fim which restarts the
237 breakpointed operation.
238 
239 Breakpoints may be set within BCE also.  However, they should be set
240 only at the "boot" command level.  When set at the "early" command
241 level, a breakpoint will cause a return to the "early" command level.
242 Also, a breakpoint set at the "crash" level is useless since, upon a
243 breakpoint/crash of the "crash" command level, the toehold purposely
244 does not save the crash image to avoid overwriting the Multics image
245 already saved.
246 
247 
248 Notes on breakpoint references: When a breakpoint causes a return to
249 BCE, BCE does not execute the bce_command in the flagbox.  Instead, it
250 enters probe directly.  Probe will assume a default of "-break." Probe
251 may be exited at this time.  This does not effect a return to Multics
252 however, only a return to BCE ("crash" or "bce_crash") command level.
253 Probe may also be entered with the control argument "-break" to force
254 examining the breakpoint conditions.  The only difference between
255 "-break" and "-crash" for probe is the machine conditions to use.  The
256 "-crash"control argument uses registers contained within the toehold
257 when the toehold was invoked.  These registers are most interesting
258 when BCE is manually entered.  The "-break" control argument uses the
259 registers at the time of the breakpoint; these were saved by the
260 breakpoint handler.  The registers will show the register contents at
261 the time of the breakpoint; however, the instruction counter will show
262 the relocated instruction, not its original location.