04/21/86  probe, pb

Syntax as a command:  pb {-control_arguments}


Function:  is used to examine, patch and generally debug the Multics
hardcore and BCE itself, as well as providing a general memory and disk
patch/dump facility.  Its requests resemble those of the Multics probe
command.  It can be used at all BCE command levels.


Control arguments:
-bce
   examines bce itself.
-break
   examines the active breakpoint.
-crash
   examines the saved crash image.

When probe is invoked at the "boot" command level, the default is to
examine BCE.  When probe is invoked automatically upon encountering a
breakpoint, the default is to examine the breakpoint.  Otherwise, the
default is to examine the crash image.


Notes:  The BCE probe command reads request lines from the bootload
console.  Multiple requests may appear on one line separated by
semi-colons.  The syntax of these requests varies from request to
request.  The recognized requests are listed below.  Various other
aspects of BCE probe are described in the following sections.


List of address forms:  Several requests in BCE probe take an address
describing what should be displayed, modified, etc.  These addresses
can take many forms, depending on what is desired.  Valid address forms
are:
N
   specifies absolute memory location N.  N may describe any location
   in all of memory.  N is specified in octal.
M|N
   specifies the virtual location N in segment M.  The interpretation
   of this virtual address depends on the address space being examined;
   refer to the dbr and proc requests.  Both N and M are specified in
   octal.


name|N
   specifies the virtual location N in the hardcore segment with the
   specified name.  This interpretation is subject to the address space
   being examined.  N is specified in octal.
M$entry
   specifies the virtual location whose address is that of the
   specified entry in segment M.  This interpretation is subject to the
   address space being examined.  M is specified in octal.
M$entry+|-N
   specifies the virtual location offset N (plus or minus) from the
   address of the specified entry in segment M.  This interpretation is
   subject to the address space being examined.  Both M and N are
   specified in octal.


name$entry
   specifies the virtual location whose address is that of the
   specified entry in the hardccore segment with the specified name.
   This interpretation is subject to the address space being examined.
name$entry+|-N
   specifies the virtual location offset N (plus or minus) from the
   address of the specified entry in the hardcore segment with the
   specified name.  This interpretation is subject to the address space
   being examined.  N is specified in octal.
.{+|-N}
   specifies the last location referenced (of any address type)
   optionally offset by the value N.  N is specified in octal.


reg(name)
   specifies the named register in the crash image.  This address is
   not valid when examining the live BCE.  Valid registers are:

         prN (N = 0 to 7)
         xN (N = 0 to 7)
         a, q, e
         t, ralr
         fault, ext_fault, mode, cache
         dbr, bar

disk(drive_name,record_num,offset)
   refers to a specific page of a disk drive.  The drive name is in the
   standard form: dska_04, or dskb_00a (subvolume device) for example.
   Both record_num and offset (within the page) are specified in octal.


List of probe requests:
before {address}, b {address}
   sets a breakpoint to be executed before executing the instruction at
   the specified address.  If no address is specified, "."  is assumed.
   The address must be a virtual address.  The breakpoint is added to
   the list of breakpoints for the segment.  Up to 120 breakpoints may
   be set per hardcore segment; however, all wired hardcore segments
   share the same breakpoint area so only 120 breakpoints in total may
   be set in wired segments.
continue, c
   continues the saved image from a breakpoint.  It is the same as
   exiting probe and entering the continue command.  Multics is
   restarted.


dbr {value1 {value2}}
   sets the dbr (descriptor base register) value used in the appending
   simulation used to access virtual addresses in the Multics image.
   If value2 is omitted, the second word of the dbr value is obtained
   from the dbr in effect when Multics crashed.  Both value1 and value2
   are octal values.


display address {mode {length}}
ds address {mode {length}}
   displays a set of locations in a specified mode.  If length is
   omitted, a value of 1 is assumed.  For virtual addresses, a length
   of "*" may be specified to display to the end of the segment.  If
   mode is omitted, octal is assumed.  Valid modes are:

         a - ASCII characters
         d - decimal words
         i - instruction format
         o - octal words (default)
         p - symbolic pointer (double words)


   The locations are displayed four to a line in the desired format.
   The value of "."  after this request finishes is the first location
   displayed.
let address = value {...  value}
l address = value {...value}
   modifies a series of locations starting at the address specified.
   Each value is converted to a number of words and catenated together
   to form the new value.  Valid values are:
   STR
      a quoted string of characters.  To place a quote character into
      the string, it must be doubled.
   N
      a decimal number.


   No
      an octal number.
   Nb
      a binary number.
   M|N
      a pointer to segment M offset N (double word).
   name|N
      a pointer to the named hardcore segment offset N (double word).
list_requests, lr
   lists the valid BCE probe requests.
mc address {-long}
mc address {-lg}
   displays, in interpreted form, the SCU data found within the machine
   conditions at the specified address.  Specifying -long also dumps
   the machine registers from the machine conditions.


name segno
   displays the name of the hardcore segment with segment number segno.
proc N
   changes the address space used by the appending simulation for
   displaying virtual addresses to the Nth process in the active
   process table.  A value of 1 specifies the Initializer's process.
quit, q
   exits probe.
reset {address}
r {address}
   resets a given breakpoint; that is to say, Multics will no longer
   break when the instruction is encountered.  The breakpoint causing
   the return to BCE can be reset by not specifying an address.


segno name
   displays the segment number of the named hardcore segment.
stack address
sk address
   displays a stack trace starting at the given address.  If the word
   offset of the address is 0, the address is assumed to refer to a
   stack header.  Otherwise it is assumed to refer to a stack frame.
   For each frame, the stack frame offset, entry pointer, return
   pointer and argument pointer is displayed.
status {name|segno}
st {name|segno}
   either lists all segments with breakpoints set in them (if no name
   or segno is specified) or lists all offsets within a single segment
   at which a breakpoint is set.


Notes on hardcore breakpoints:  The hardcore breakpoint facility is a
collection of facilities within Multics and BCE that allow probe style
breakpoints to be set at most BCE and hardcore instructions.  They may
be used largely as they are within normal Multics probe, with a few
cautions.


Notes on breakpoint mechanism:  The following paragraphs describe the
mechanism by which hardcore breakpoints are implemented.  An
understanding of this mechanism will prevent the user from setting a
breakpoint in an incorrect path; in particular, breakpoints may not be
set in the breakpoint handler's path.


When a hardcore breakpoint is set at an instruction, the instruction at
that location is relocated to the end of the segment containing it.
Its addressing is changed to reflect its new location.  The original
location is replaced with a transfer instruction to a breakpoint block
at the end of the segment which executes a "drl -1" instruction.  This
causes the breakpoint to happen.  If the breakpoint handler returns
without changing the breakpoint, the next instruction in the block will
be executed.  This is the relocated original instruction.  After this,
a transfer is made back to the correct place in the original program.
It should be noted that the instruction moved cannot be the second or
later words of an eis multi-word instruction.


Derail faults are handled in fim.  A "drl -1" instruction is
special-cased to be a breakpoint.  Fim makes a call to
pmut$bce_and_return to implement the call to BCE.  Any program in this
path cannot have a breakpoint placed within it.  In other words, a
breakpoint cannot be set in the path of code which gets executed
between a breakpoint and a return to BCE.  This path includes the
breakpoint handler in fim, the code in pmut$bce_and_return, any code
which sends and handles connects to other processors, etc.  Also, the
special casing of a "drl -1" to be a breakpoint only applies for
derails in ring 0.  Thus, breakpoints should not be set in segments
that will be executed in other rings.


When BCE is invoked via the toehold, it notices that a breakpoint was
the cause of the return to BCE and invokes BCE probe directly.  Probe
is free to perform a continue operation which eventually returns to
pmut, restarts other processors, and returns to fim which restarts the
breakpointed operation.

Breakpoints may be set within BCE also.  However, they should be set
only at the "boot" command level.  When set at the "early" command
level, a breakpoint will cause a return to the "early" command level.
Also, a breakpoint set at the "crash" level is useless since, upon a
breakpoint/crash of the "crash" command level, the toehold purposely
does not save the crash image to avoid overwriting the Multics image
already saved.


Notes on breakpoint references: When a breakpoint causes a return to
BCE, BCE does not execute the bce_command in the flagbox.  Instead, it
enters probe directly.  Probe will assume a default of "-break." Probe
may be exited at this time.  This does not effect a return to Multics
however, only a return to BCE ("crash" or "bce_crash") command level.
Probe may also be entered with the control argument "-break" to force
examining the breakpoint conditions.  The only difference between
"-break" and "-crash" for probe is the machine conditions to use.  The
"-crash"control argument uses registers contained within the toehold
when the toehold was invoked.  These registers are most interesting
when BCE is manually entered.  The "-break" control argument uses the
registers at the time of the breakpoint; these were saved by the
breakpoint handler.  The registers will show the register contents at
the time of the breakpoint; however, the instruction counter will show
the relocated instruction, not its original location.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved