The inside story - updated for *MDUMP v1.05
===========================================

Most DFS provide a *DUMP command to list the contents of a file in both
hexadecimal and in characters. This routine provides a command - *MDUMP -
which does exactly the same with an area of memory, not just main memory,
but sideways ROM, shadow RAM and the Tube.

The listing generates the MDUMP command file. Type it in and check it with
Get it Right! When run it generates the code and saves it as MDUMP.

The command is called by entering:

        *MDUMP addr end
or
        *MDUMP addr + length

All the address are given in hexadecimal, and tape users should use */MDUMP
wherever a reference to *MDUMP is made.

To dump 16 bytes of memory starting at &700, you could use:

        *MDUMP 700+10

or

        *MDUMP 700 710

As this is the area of memory used by BASIC to hold the command line just
typed in, you will see something like:

        000700 2A 4D 44 55 4D 50 20 37 *MDUMP 7
        000708 30 30 20 2B 31 30 0D 00 00 +10..

Giving the start address in the format FFrrssss causes ROM number rr to be
paged in and dumped, so:

        *MDUMP FFFD8000+20

dumps the first 32 bytes of ROM 13. A start address of FF8xxxxx will select
the VDU workspace RAM that overlays the sideways ROMs. On a Master, doing:

        *MDUMP FF808000+20

will show the start of the function key definitions.

If you have a second processor attached, then addresses in the FFxxxxxx
range will address the I/O processor's memory, as with filing system
addresses, so:

        *MDUMP FFFF3000+40

will dump the start of the area of memory reserved for the screen in the
I/O processor. Also:

        *MDUMP F800 FFFF

will dump the second processor operating system on a 6502 second processor.

A start address of FFFExxxx and FFFDxxxx will dump shadow screen memory.
FFFExxxx dumps whichever memory is being used to display the screen, and
FFFDxxxx dumps the shadow screen memory whether it is being used to display
the screen or not.

*MDUMP will also dump the shadow screen memory on a BBC with any system
that uses the OSBYTE 111 call allocated for paging in video memory, such as
the Aries B-20/B-32, Integra-B and Watford Shadow RAM. Unfortunately, it is
not possible to easily access the shadow memory on the BBC B+ as it cannot
be accessed by code other than the VDU drivers.

The BBC B+ and Master series have more memory hidden away inside them as
well as the shadow screen memory. There's spare memory left over from the
screen memory that is used for private workspace RAM. Given an address in
the format FF8xssss, the *MDUMP command will dump this memory.

So, the full range of addresses is:

{*} FFFF0000 to FFFFFFFF - main memory
{*} FFFE3000 to FFFE7FFF - the currently displayed screen
{*} FFFD3000 to FFFD7FFF - the shadow screen memory
{*} FFFr8000 to FFFrBFFF - sideways ROM/RAM number r
{*} FF8x8000 to FF8xAFFF - the spare sideways RAM on the BBC B+
{*} FF8x8000 to FF8x8FFF - the VDU workspace RAM on the Master
{*} FF8xC000 to FF8xDFFF - the filing system RAM on the Master
{*} FFCxFC00 to FFCxFEFF - the hidden MOS ROM on the Master

The table on the following page gives a summary of the addresses you can
use with the *MDUMP command.

        +----------+--------------+--------------+--------------|
        | Address  |    BBC B     |    BBC B+    |    Master    |
        +----------+--------------+--------------+--------------+
        | 00000000 |   Normal language memory, ie main memory   |
        |    to    |       if no second processor, second       |
        | FEFFFFFF |        processor memory if there is.       |
        +----------+--------------+--------------+--------------+
        | FF8x8000 |              |              |    MOS and   |
        |    to    |              |              |      VDU     |
        | FF8x8FFF |              |    Spare     |   workspace  |
        +----------+              +   sideways   +--------------+
        | FF8x9000 |   Sideways   |    memory    |              |
        |    to    |     ROM x    |              |              |
        | FF8xAFFF |    memory    |              |   Sideways   |
        +----------+              +--------------+    ROM x     +
        | FF8xB000 |              |   Sideways   |    memory    |
        |    to    |              |     ROM x    |              |
        | FF8xBFFF |              |    memory    |              |
        +----------+--------------+--------------+--------------+
        | FF8xC000 |              |              |    Filing    |
        |    to    |   MOS ROM    |   MOS ROM    |    system    |
        | FF8xDFFF |              |              |  workspace   |
        +----------+--------------+--------------+--------------+
        | FF8xE000 |             Machine Operating              |
        |    to    |                System ROM                  |
        | FF8xFFFF |         and memory mapped I/O ports        |
        +----------+--------------+--------------+--------------+
        | FFCxC000 |      Machine Operating      | MOS ROM with |
        |    to    |         System ROM          |  I/O ports   |
        | FFCxFFFF | and memory mapped I/O ports |  paged out   |
        +----------+--------------+--------------+--------------+
        | FFFD3000 |    Shadow    |     Main     |    Shadow    |
        |    to    |    screen    | I/O processor|    screen    |
        | FFFD7FFF |    memory    |    memory    |    memory    |
        +----------+--------------+--------------+--------------+
        | FFFE3000 |    Current   |     Main     |    Current   |
        |    to    |    display   | I/O processor|    display   |
        | FFFE7FFF |    memory    |    memory    |    memory    |
        +----------+--------------+--------------+--------------+
        | FFFF0000 |         Main I/O processor memory,         |
        |    to    |            and non-shadow screen           |
        | FFFF7FFF |                   memory.                  |
        +----------+--------------+--------------+--------------+
        | FFFx8000 |                                            |
        |    to    |         Sideways ROM/RAM number x.         |
        | FFFxBFFF |                                            |
        +----------+--------------+--------------+--------------+
        | FFFFC000 |                                            |
        |    to    |        Machine Operating System ROM        |
        | FFFFFFFF |                                            |
        +----------+--------------+--------------+--------------+

          The addresses to use to dump various areas of memory


The program has been tested on BBC B and B+, Electron, Master and Compact,
on all operating systems from 1.20 onwards, and with several DFSs including
DFS 0.90 and 1.20. It has been tested with Aries, Integra-B and Watford
shadow screens. It will work with NFS 3.60, but the NFS 3.34 ROM has a bug
in the routine to return the address of the command line, so it will not
work. If you have that ROM you should take advantage of the service offered
by many companies cheaply - or freely - to upgrade it.


How it works
------------
The first part of the program calls the filing system to get the address of
the parameters on the command line. It then checks that the first is a
valid hexadecimal address and reads it in to the zero page locations addr
to addr+3.

The following parameter is checked if it is preceeded with a '+', then the
following address is fetched. It it was preceeded by a '+' then it is added
to the start address to get the end address.

If there is deviation from the expected syntax, then the error message

        Syntax: MDump <start> (<end>|+<length>)

is given. As the first part of the program is only executed once, this is
used later as variable space to save memory and squeeze it into 512 bytes
so it will fit in the cassette buffer.

The next section of the program checks which machine it is running on by
using OSBYTE 0 so the code that reads from memory can set I/O settings
accordingly.

The shadow screen is accessed using OSBYTE 108 on the Master and OSBYTE 111
on the BBC. OSBYTE 108 is called first and its return value is checked. If
X is &FF the call does not exist and OSBYTE 111 is then tried.

The BBC B+ accesses its extra sideways memory by setting the ROM/RAM select
latch at &FE30 to 128. The Master accesses its extra memory by changing
different bits of the ACCCON register at location &FE34.

For an explanation of the ACCCON register, see the New Advanced User Guide,
Dickens & Holmes. It is sufficient to say that on the BBC B+, bit 7
controls whether shadow screen is paged in, and on the Master bits 2 and 3
control whether the shadow RAM and filing system workspace RAM are paged in
or not. As the other bits also affect the system's setup, they have to be
preserved when changing bits 2 and 3.

The program goes into a loop which does the following:

{*} The current address is printed.
{*} A number of bytes are fetched into the buffer. They are printed in
hexadecimal.
{*} The bytes are then printed in characters. Ones in the range 128 to 255
are displayed as characters 0 to 127, where characters 0 to 31 (the control
codes) and character 127 (delete) are displayed as full stops.
{*} The Escape flag is checked, and if Escape has been pressed, it is
cleared and the program exits.
{*} Otherwise, the current address addess is updated.
{*} The current address is compared with the end address. If the top 12
bits do not match, the start of the loop is jumped back to to display
another line.

Use of OSBYTE 0

OSBYTE 0 tells you what operating system the machine is running. When
entered with X=0, an error message is displayed with the version. With X as
non-zero, then X is returned holding a number refering to the OS number. 
These are:

  0  Electron
  1  BBC micro, OS 1.00, OS 1.20
  2  BBC B+, OS 2.00
  3  BBC Master, 3.20
  4  BBC Master, OS 4.00
  5  Master Compact, OS 5.00

This is similar to INKEY(-256), but gives an easier series of numbers to
decode.

Technical notes
---------------
Bits 16 to 23 of the memory address form a bitmap which selects various
banks of memory as follows:

  Address    &0000-&7FFF   &8000-&BFFF   &C000-&FBFF  &FC00-&FDFF   
 <&FFxxxxxx  lang memory   lang memory   lang memory  lang memory  MemArea+&40
  &FF0rxxxx  main memory   SROM/SRAM r   FS RAM         MOS ROM      0100rrrr
  &FF2rxxxx  main memory   SROM/SRAM r   FS RAM           I/O        0110rrrr
  &FF4rxxxx  main memory   VDU RAM       MOS ROM        MOS ROM      1000rrrr
  &FF6rxxxx  main memory   VDU RAM       MOS ROM          I/O        1010rrrr
  &FF8rxxxx  main memory   VDU RAM       FS RAM         MOS ROM      1100rrrr
  &FFArxxxx  main memory   VDU RAM       FS RAM           I/O        1110rrrr
  &FFCrxxxx  main memory   SROM/SRAM r   MOS ROM        MOS ROM      0000rrrr
  &FFErxxxx  main memory   SROM/SRAM r   MOS ROM          I/O        0010rrrr
  &FFFExxxx  display mem   SROM/SRAM r   MOS ROM          I/O        |||  ||
  &FFFFxxxx  main memory   SROM/SRAM r   MOS ROM          I/O        |||  ||
                                                                     |||  ||
                                                            SROM/VDU-+||  ||
                                                            MOS/FSRAM-+|  ||
                                                            MOS/IO-----+  ||
                                                            ROM number----++