AtoMMC2

An SD/MMC card interface for Acorn Atom computers
by SirMorris / EightyBits  2010-2011
revised and updated : Phill Harvey-Smith 2012.

Introduction
AtoMMC2 provides modern mass storage for the classic British Atom computer.
It is a combination hard/software solution designed to fit inside the
Atom's case without unusual modifications to the machine. As of version 
2.0 it provides full read and write access to files on a FAT formatted 
MMC or SD/SDHC card.

It will work on any Atom computer as it doesn't require RAM, ROM or
hardware
expansions.

This guide assumes firmware version 2.9 is installed in both Atom and
interface.

Atom Firmware.
-------------

There are 2 available versions of the Atom firmware. One is configured
as a service ROM and occupies the memory map in the utility ROM space of
#A000->AFFF. The second is recommended for users of memory expansion
systems with the ability to put code in the DOS ROM memory region at
#E000. It requires two small patches to the Atom kernel ROM and
naturally precludes the use of Atom DOS without appropriate ROM switching.

Atomulator currently only supports the #E000 firmware.

The A000 firmware.
------------------

This version resides in a 2532 EPROM and should be fitted in the socket
marked IC24. Orientation is indicated by the notch in the chip's casing.
It should be placed to match the chips around it. Please ensure that the
EPROM's legs are not bent during fitting. If any do suffer an unexpected
angular distortion, then straighten the affected pin(s) by placing the
chip with its legs flat against a solid, flat surface. Gently press the
bent leg back into alignment and try again. No damage should occur if
the machine is powered up with a bent pin, but the software will fail.
In order for the code to initialise on reset it is necessary for the
Atom to receive interrupts generated by the interface board. This may
require the fitting of LK3 - a short wire link located to the right of
PL8. Without this connection, or with interrupts disabled viaconfiguration, 
the firmware will have to be initialised manually by typing the following 
after each reset:

LINK#AFCC

The E000 firmware.
------------------

Users of memory expansion boards should follow the procedure for burning
the patched kernel and #E000 images into their system. The patched
kernel will initialise the firmware at the right time and so no
interrupts are needed. LK3 may be left unmade or interrupts can be
disabled in the firmware. See the CFG command.

Initialisation
--------------

Once the interface and firmware are fitted the machine can be powered up
and you should be greeted with a banner announcing the presence of the
interface.

ACORN ATOM + ATOMMC2

Holding various keys when hitting BREAK will have effects:
	CTRL 	will disable the interface firmware until next reset.
	SHIFT 	will try to execute a file called MENU
	REPT 	will show additional information such as the firmware revision
			and type of card inserted.

Adding software to the card
---------------------------

Files are simply added to the card using your choice of operating
system. Subdirectories are  supported, however long filenames are not.

The DOS 8.3 format should be used at all times.

The 'ATM' format is used to ensure Atom files carry their required
metadata. It is a 22 byte header conforming to the following standard:

Offset		Purpose
$00 - $0F	File name - Up-to 12 bytes of name + zero padding
$10 - $11	Load address
$12 - $13	Exec address
$14 - $15	Length


Here's the header from Snapper showing the 22 header bytes and the first
10 characters of the main program:

53 4E 41 50 50 45 52 00 00 00 00 00 00 00 00 00 SNAPPER
00 29 86 CE 00 13 0D 00 00 52 45 4D 2F 2F 20 53

The 16 bit values are stored in little-endian form.

Firmware reference
------------------

All numeric parameters are specified in hex. No qualifiers such as # or
$ are needed. 

Filenames being passed as parameters to '*' commands do not need quotes. 

The patched OS routines LOAD and SAVE require them.

Optional parameters are shown in parenthesis.

*CAT [*.] (<directory name>) (@<filter character>) 
*CAT [*.] (wildcard)

Show a listing of files.

If a directory name is specified then the files in that directory will
be listed, otherwise only the files in the current working directory
will be shown.

You may specify a wild-card character to filter the output. For example,
to show only the files starting with the letter Q use the following command:
*CAT @Q

Both a filter and a path may be specified. Order is unimportant. The
following commands are equivalent:

*CAT GAMES @S 
*CAT @S GAMES

Relative paths are supported. The directory separator token may be
specified as '/' or '\'. Used alone this token specifies the root
directory. The token . Represents the current directory, and ..
represents the parent directory, exactly like MSDOS.

Alternatly from firmware version 2.9 onwards you may use a DOS / Unix
stle wildcard specification including paths such as :

*CAT GAMES\SN*

Would list all files in the games directory starting with SN

Files with their DOS hidden attribute set are never shown. This is
useful for hiding data files. Press SHIFT or REPT to pause a long
listing. ESC will abort the listing.


*CWD [*CW.] <filename>

Change the current working directory (CWD).
Once the CWD is changed, all file operations are carried out relative to
this path.


*INFO [*I.] <filename>

Show the ATM metadata associated with a file.
The metadata is stored in the first 22 bytes of a file. If none is
present then junk will be printed as there is no way to know if data is
present or not. You should see something like:

SNAPPER	2900 CE86 1300

This shows the load address to be #2900, its execution address to be
#CE86 and the file length to be #1300 bytes.


*FATINFO [*F.] <filename> 

Show the raw file system information for a file.
The first value shown is the file length in hex. Next is the start
sector for the file. A reserved value of zero follows, then the DOS
attribute byte.


LOAD "<filename>"
Load a program into the currently selected text page.
The file's metadata is printed unless suppressed with the command *NOMON.


*LOAD [*L.] <filename> (<load address>) 

Load a program exerting control over its placement in memory.
Omitting the load address will load the file into the location specified
in its metadata, otherwise data will be placed in memory starting at the
specified address.

The file's metadata is printed unless suppressed with the command *NOMON.

This command will load the file from the card using the file system
length rather than any metadata information. As such the address is
mandatory.

The file's metadata is printed unless suppressed with the command *NOMON.


*RUN [*<filename>] <filename> (<parameter>...<parameter>)

Load and attempt to execute a program.

The firmware attempts to run all programs even if they were not intended
to be auto-running. In some cases this will produce an error in which
case the normal load.run sequence should be used.

Any parameters following the filename will be relocated to the input
buffer at #100. If no parameters are given #100 will contain return (#0D).


*EXEC [*E.] <filename>

Present the specified file's content to the Atom as if it had been typed.

Files read in this way should be ANSI text files. This is a useful way
of entering programs which only exist as listings.


SAVE "<filename>" 

Save the current program.
Memory from the start of the current text page to the value of TOP is
written to the specified file. If a file with the same name already
exists you will be prompted to overwrite it.


*SAVE [*S.] <filename> <start> <end> (<exec>) 

Save a block of memory.

The end address is exclusive - in other words it is the address of the
last byte to be written + 1. The execution address will be set to the
start address if not specified.

*DELETE <filename>

Delete the specified file from the card.

*HELP [*H.]

Show some useful information.


The remaining commands are related to the operation of the interface.


*CFG [*C.] (<value>) 

Set/get interface configuration bits.
Specifying a value will set the configuration bit values, omitting it
will cause the current configuration value to be displayed. All values
are specified and shown in hex. The default value is FF. The following
bits have an effect:

Bit		Hex		Purpose
5		20		Enable Interrupts
6		40		Shift-Break Action
7		80		Enable Boot loader

In order to disable interrupt generation the following command could be
issued: 

*CFG C0

Warning: Extreme care should be taken when changing the configuration
bits. Certain combinations may have undesirable effects on the operation
of the hardware. 

The most dangerous combination is disabling the boot loader when no 
firmware is flashed. This will result in an endless loop which cannot 
be aborted. The only way to reverse this action is to remove the PIC 
and use a dedicated PIC programmer to change the configuration byte 
in EEPROM.

Holding shift at boot-time will insert the string '*MENU' into the
keyboard buffer and thus try to execute a program with that name. It may
be desirable to have this done on every reset, and so you can invert the
shift-key detection sense with bit 6. This way the menu is executed
unless the shift key is held.

The interface features an 8-bit bidirectional user port  known
affectionately as PORTB. The data direction for each pin on the port is
independent and user selectable. The directions and values are stored in
EEPROM and will be restored on power-up.

(Port B is currently unsupported by Atomulator, though the port configuration
commands will still work, and save the port B settings in the emulated EEPROM)


*PBD (<value>)

Set/get the PORTB direction configuration.

1 is 1nput, 0 is 0utput. FF will set all pins to input. 0 will set all
to output.


*PBV (<value>)

Set/get the state of the PORTB pins.

Setting the state of a pin which is configured as an input will latch
the specified value but otherwise have no effect. Reading the state of a
pin set as an output will show the value last latched to that pin. The
port will sink way more current than it can source, so it is recommended
to use the port in open collector mode:- make the pin an input and tie
the driven line high using a resistor. Change the port to output and
drive it low in order to present a logic low level.

Here is a diagram showing the pin ordering on the board. The view is of
the main interface PCB, top-left component side.
Pin 7	Pin 0
V	V
+---|||||||| 	...
| ++++++++ |

Upgrading the firmware
----------------------

Note the PIC firmware is built into Atomulator, and so cannot be upgraded 
without re-compiling the emulator.

The interface firmware may be upgraded using the built-in boot loader.

The procedure is as follows:
* Ensure the version of the firmware being flashed is compatible with
  the available Atom firmware.
* Ensure the boot loader is enabled.
* Obtain the latest PIC firmware files.
* Format a card and copy the 3 firmware files to it.
* Insert the card and reset the Atom.
* The interface will light both LEDs and flash the green whilst the
  firmware is flashed.
* The LEDs will extinguish. Remove the card and reset the Atom.

The boot loader is robust but there may be combinations of firmware
updates which require further steps. Call your support representative
for further assistance.


Troubleshooting
---------------

If no banner is shown at reset:
A000 version: 
	Check that interrupts are enabled

E000 version: 
	Ensure ROM is correctly loaded and that the kernel ROM is patched.

Solid green light on reset: 
	Re-flash firmware.

CARD? is shown when accessing the card:
	Try a different brand of MMC/SD/SDHC card.

No response from interface / card accesses hang:
	Ensure dongle connections are correct, ensure PL8 connection is correct.

Flames come from Atom case:
	Remove/bypass regulators and supply a healthy 5V.
