The Magic7 Monitor

This document describes the monitor within the Magic7 Cheops operating system. It allows for various low level debugging and multi-tasking process control operations.

The Monitor as a Process

The Magic7 operating system allows for many processes to run in a multi-tasking format. One of these processes is always the monitor, which is polling its input ports (both serial and SCSI) for user input and handling any monitor commands.

Command Line Input to the Monitor

A Cheops terminal emulator is available for use as a "window" to the Cheops monitor. This is invoked through the command alias cheops, which is set up in the Cheops user environment (see document Setting Up the Cheops Programming Environment) When you type cheops from a host which is connected to Cheops, you will get the Cheops monitor. Hit return a few times and you should get the Magic7 prompt. It looks something like:

Magic7 m0s4p0S>

This prompt provides command line input into the Cheops Magic7 Monitor. The "m0s4p0S'' means that you are connected to processor module 0, with SCSI device number set to 4; the monitor is running as process number 0 (which should be the case unless you have loaded a new version of the Magic7 into RAM and are running that instead of the ROM version -- then you will get "p1") and it is sleeping unless you type something at it (the default). If you have problems, the system is probably not set up correctly. See the document Cheops Hardware Introduction.

NOTE: Control-a is specially wired to a soft-reset. Try it, and you will see the Cheops Monitor reset welcome signature.

Monitor Commands

A wide variety of commands are available in the Monitor. These are described here in four groups:

1. Multitasking commands
2. View Data commands
3. Debugger commands
4. Miscellaneous commands

NOTE: You may see a list of all the commands in any of these groups by typing `he1', 'he 2', etc., from the Monitor command prompt. Simply typing `he' will display the above list of command groups.

Multitasking Commands

Magic7 supports process multitasking. The following commands allow for direct control of downloading, running, halting, and killing processes. These are low level commands and are only used if you are "hand-downloading" your code and setting it into execution by hand. These are brief with the assumption that you understand the Magic7 multitasking system. For further detail on the multitasking system, see the document The Magic Seven Multitasking System.

rb

ROM boot. Boot from ROM kernel as opposed to booting from the version in RAM if one is loaded and running.

sb (or control A)

Soft RAM boot. Boot from the RAM kernel if one is running, otherwise boot the ROM version.

do < proc_no>

Download a new process using xmodem. It waits for you to hit (ctrl-[) and type the full path of the name of the file you want to download. This type of executable must have fixed addresses. The standard Cheops makefile creates a file with the extension `.t', which can be downloaded using the `do' command. Look at the Makefile for the line:
FIXED = -Ttext 300d0000
This address is where the code is downloaded. Notice that sometimes the compiler reserves the first area of memory at this location for data, so you'll need to adjust the starting location with the cr command. A downloaded file will be set to HALTED mode.

go

Initialize and start a downloaded process. This should only be used in pre-multitasking versions of the monitor (before version 2.0). You'll probably never use this.

sp < proc_no>

Initialize a process which is in memory, but is not yet recognized by the multitasking system.. Puts into HALTED mode. For example, if you rm a process, it is killed but is still in the actual memory (unles something has written over it). The sp command, in conjunction with the cr command (which you must designate the exact address) allows you to declare a new process.

rm < proc_no>

Remove process from proc table. Sets its state to NULL.

ha < proc_no>

Halt process. Can be re-started.Sets the process state to HALTED.

rs < proc_no>

Start or restart a halted process. Begins execution at the return address (labelled RIP in the ps table) and sets the process state to ACTIVE.

cd < proc_no>

Changes current debug process.

cr < proc_no>

Change return address of process. Use this to set the entry point of execution the next time that process state becomes ACTIVE.

ts

Toggle sleep.

sl

Force a sleep. Notice that whenever you enter a monitor command, the Monitor Process is the active one. So you can only "sleep" the monitor.

ps

Print out status of all the process states. This is a very useful little table which shows each process, its state, and its return address, as well as its ASCII name.

cc

Print out status of all memory cells allocated by 2D cell_malloc.

The ramlog utility is the preferred method for real-time debugging. The monitor has a command to enable, disable, and display the log information:

rl < init | start | stop | clear | dump >

The trace and breakpoint utilities have never been completely proven functional. But here are all the commands which you can use at your own risk:

da < addr> # < n>

Disassemble one or more instructions

tr < option> < on|off>

Turn on or off one of the following trace options: branch, call, return or supervisor call.

br < addr>

Set instruction break.

bd < addr>

Set data break

bx < addr>

Delete instruction break

by < addr>

Delete data break

ox < card> < mode>

Initialize a selected output card to a desired video configuration.

oc < XXBBGGRR>

Clear output card 0 to the color R,G,B. (o0, o1, o2, o3 clear selected output modules).

cb

Display color bars on output module 0. The bars are sized to fit the current video configuration.

ve

Print version header.

pp

Prints port status. This displays a table which shows the status of each port and what processes it connects.

ss

Prints a table showing the status of semaphores.

cc < bank>

Shows the cell_malloc configuration of a selected memory bank.

. (one period)

Repeat previous instruction

.. (two periods)

Repeat post-previous instruction

sx

Initialize the SCSI interface. Typically fatal in everyday use.