#### 6.2.2 Debug commands ¶

Sequential execution of loaded programs can be interrupted using the following debug commands:

debug command: next [ins_number] ¶

  This command causes the virtual machine to fetch and execute up to ins_number instructions, beginning from the current program counter position. Execution is interrupted either when the specified number of instructions have been fetched or a breakpoint is found, whatever happens first. If run without arguments, one instruction is executed. If `next` is invoked again after program execution completion (i.e., after the `HLT` instruction has been found in a previous run), the program counter is repositioned and execution starts again from the beginning (as a matter of fact, a `load` command preserving the currently set breakpoints is issued before resuming execution).

debug command: sbp line_number ¶
debug command: cbp line_no ¶

  Sets a breakpoint at the specified source file line number. If the line specified corresponds to a command or to a MIXAL pseudoinstruction which does not produce a MIX instruction in the binary file (such as `ORIG` or `EQU`) the breakpoint is set at the first source code line giving rise to a MIX instruction after the specified one. Thus, for our sample `hello.mixal` file:

      *                                                        (1)
      * hello.mixal: say 'hello world' in MIXAL                (2)
      *                                                        (3)
      * label ins    operand     comment                       (4)
      TERM    EQU    19          the MIX console device number (5)
              ORIG   1000        start address                 (6)
      START   OUT    MSG(TERM)   output data at address MSG    (7)
      ...

  trying to set a breakpoint at line 5, will produce the following result:

      MIX > sbp 5
      Breakpoint set at line 7
      MIX >

  since line 7 is the first one compiled into a MIX instruction (at address 3000).

  The command `cbp` clears a (previously set) breakpoint at the given source file line.

debug command: spba address ¶
debug command: cbpa address ¶

  Sets a breakpoint at the given memory address. The argument must be a valid MIX memory address, i.e., it must belong into the range [0-3999]. Note that no check is performed to verify that the specified address is reachable during program execution. No debug information is needed to set a breakpoint by address with `sbpa`. The command `cbpa` clears a (previously set) breakpoint at the given memory address.

debug command: sbpr A | X | J | Ii ¶
debug command: cbpr A | X | J | Ii ¶

  Sets a conditional breakpoint on the specified register change. For instance,

      sbpr I1

  will cause an interruption during program execution whenever the contents of register `I1` changes. A previously set breakpoint is cleared using the `cbpr` command.

debug command: sbpm address ¶
debug command: cbpm address ¶

  Sets a conditional breakpoint on the specified memory cell change. The argument must be a valid MIX memory address, i.e., it must belong into the range [0-3999]. For instance,

      sbpm 1000

  will cause an interruption during program execution whenever the contents of the memory cell number 1000 changes. A previously set breakpoint is cleared using the `cbpm` command.

debug command: sbpo ¶
debug command: cbpo ¶

  Sets/clears a conditional breakpoint on overflow toggle change.

debug command: sbpc ¶
debug command: cbpc ¶

  Sets/clears a conditional breakpoint on comparison flag change.

debug command: cabp ¶

  Clears all currently set breakpoints.

debug command: psym [symbol_name] ¶

  MIXAL programs can define symbolic constants, using either the `EQU` pseudoinstruction or a label at the beginning of a line. Thus, in the program fragment

      VAR     EQU  2168
              ORIG 4000
      START   LDA  VAR

  the symbol `VAR` stands for the value 2168, while `START` is assigned the value 4000. The symbol table can be consulted from the `mixvm` command line using `psym` followed by the name of the symbol whose contents you are interested in. When run without arguments, `psym` will print all defined symbols and their values.

The virtual machine can also show you the instructions it is executing, using the following commands:

debug command: strace [on|off] ¶

  `strace on` enables instruction tracing. When tracing is enabled, each time the virtual machine executes an instruction (due to your issuing a `run` or `next` command), it is printed in its canonical form (that is, with all expressions evaluated to their numerical values) and, if the program was compiled with debug information, as it was originally typed in the MIXAL source file. Instruction tracing is disabled with `strace off` command. A typical tracing session could be like this:

      MIX > strace on
      MIX > next
      3000: [OUT	3002,0(2:3)]	START	OUT	MSG(TERM)
      MIXAL HELLO WORLD
      Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
      MIX > next
      3001: [HLT	0,0]		HLT
      End of program reached at address 3002
      Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
      MIX > strace off
      MIX >

  The executed instruction, as it was translated, is shown between square brackets after the memory address, and, following it, you can see the actual MIXAL code that was compiled into the executed instruction. The tracing behaviour is stored as a configuration parameter in `~/.mdk`.

debug command: pline [LINE_NUMBER] ¶

  Prints the requested source line (or the current one if line_number is omitted:

      MIX > load ../samples/hello
      Program loaded. Start address: 3000
      MIX > pline
      Line 5: START       OUT   MSG(TERM)
      MIX > pline 6
      Line 6:             HLT
      MIX >

debug command: sbt [NUMBER] ¶

  This command changes the limit for the backtrace of executed instructions. If the number is omitted, the command prints the current limit. If you use a 0, backtraces are turned off. This can improve performance. If you wish for all the instructions to be logged, a -1 will enable that. The amount of memory required for unlimited backtraces can be substantial for long-running programs.

debug command: pbt [INS_NUMBER] ¶

  This command prints a backtrace of executed instructions. Its optional argument ins_number is the number of instructions to print. If it is omitted or equals zero, all executed instructions are printed. For instance, if you compile and load the following program (`bt.mixal`):

          ORIG 0
      BEG JMP *+1
          JMP *+1
      FOO JMP BAR
      BAR HLT
          END BEG

  you could get the following traces:

      MIX > load bt
      Program loaded. Start address: 0
      MIX > next
      MIX > pbt
      #0      BEG     in bt.mixal:2
      MIX > next
      MIX > pbt
      #0      1       in bt.mixal:3
      #1      BEG     in bt.mixal:2
      MIX > run
      Running ...
      ... done
      MIX > pbt 3
      #0      BAR     in bt.mixal:5
      #1      FOO     in bt.mixal:4
      #2      1       in bt.mixal:3
      MIX > pbt
      #0      BAR     in bt.mixal:5
      #1      FOO     in bt.mixal:4
      #2      1       in bt.mixal:3
      #3      BEG     in bt.mixal:2
      MIX >

  Note that the executed instruction trace gives you the label of the executed line or, if it has no label, its address.

As you have probably observed, `mixvm` prints timing statistics when running programs. This behaviour can be controlled using the `stime` command (see Configuration commands).

`mixvm` is also able of evaluating w-expressions (see W-expressions) using the following command:

debug command: weval WEXP ¶

  Evaluates the given w-expression, WEXP. The w-expression can contain any currently defined symbol. For instance:

      MIX > psym START
      + 00 00 00 46 56 (0000003000)
      MIX > weval START(0:1),START(3:4)
      + 56 00 46 56 00 (0939716096)
      MIX >

New symbols can be defined using the `ssym` command:

debug command: ssym SYM WEXP ¶

  Defines the symbol named SYM with the value resulting from evaluating WEXP, a w-expression. The newly defined symbol can be used in subsequent `weval` commands, as part of the expression to be evaluated. E.g.,

      MIX > ssym S 2+23*START
      + 00 00 18 19 56 (0000075000)
      MIX > psym S
      + 00 00 18 19 56 (0000075000)
      MIX > weval S(3:4)
      + 00 00 19 56 00 (0000081408)
      MIX >

Finally, if you want to discover which is the decimal value of a MIX word expressed as five bytes plus sign, you can use

debug command: w2d WORD ¶

  Computes the decimal value of the given word. WORD must be expressed as a sign (+/-) followed by five space-delimited, two-digit decimal values representing the five bytes composing the word. The reverse operation (showing the word representation of a decimal value) can be accomplished with `weval`. For instance:

      MIX > w2d - 01 00 00 02 02
      -16777346
      MIX > weval -16777346
      - 01 00 00 02 02 (0016777346)
      MIX >