Use

Index

• Overview
• Terminology
• Quick start *
• General use *
  • Fundamentals
  • Tool tasks
  • File operations
• Special use
  • Tool tasks
  • File operations
  • ROM functions
  • Area U
• Reference
  • Parts and layers
  • Running tools
  • Star commands
  • Configuration variables
  • Error messages
  • How to recover
  • What is remembered

Overview

GoSDC-Atom is a storage system for the Acorn Atom.

It allows you to store virtually any number of files on a single flash card, and use them with vastly increased convenience and speed. Supported flash card types are MMC, SD, SDHC and SDXC. You can also soft-load a utility or extension ROM.

GoSDC is self-contained, and can make do with a completely 'bare' machine (with the full 12 KB of RAM, nonetheless).

Terminology

In the following, machine always refers to your Acorn Atom (upgraded with GoSDC), whereas PC refers to a computer running Windows, Linux or macOS.

Also, a utility/extension ROM or utility/extension or (most succinctly) UE is a piece of software that would normally be in a ROM inside the machine, but can instead be soft-loaded there (refer to Rom functions for details).

Quick start

To get a quick taste of GoSDC, proceed as follows. Everything you're asked to 'enter' is entered on your machine.

• Format a flash card
  • Pick a flash card, insert it into GoSDC's card slot and press BREAK.
  • Note that any existing flash card contents will be lost after the next step !
  • Enter  *SDCTool SDCFO  and press BREAK after.
  • Optionally, enter  *SDCInfo  and read Parts and layers.
• Save and load a file
  • Enter  10 PRINT "Hello"  and then  20 GOTO 10 .
  • Enter  SAVE "hello"  and then  LOAD "hello"  and then  RUN .

Congratulations. You have saved a file.

You can have any number of files (limited only by the flash card capacity), and you can import files from 'outside'.

General use

Fundamentals

Operating GoSDC fundamentally involves :

• Format the flash card

  You will need to do this once. Refer to Tool tasks for instructions.

• Manipulate your files

  You will do this continuously. You can use familiar COS commands (refer to File operations for more information) and some new commands (refer to File operations for more information).

Note that one physical flash card consists of up to eight logical flash cards (a.k.a. areas). For details, refer to the 'Areas' part of Parts and layers. Throughout this documentation, 'flash card' generally means logical flash card and rarely physical flash card. You can switch between logical flash cards / areas with *SDCArea.

Also note that, whenever you insert a(nother) flash card, you need not power down before, but do need to press BREAK after.

Tool tasks

You run tools to execute a variety of tasks (if needed, refer to mainly the 'Basics' parts of Running tools).

What follows documents the more common tasks (for the less common tasks, refer to Tool tasks). Note that :

• 'Native' and 'Foreign' show the command line to enter if 'Suppose' is true (and the Q in -dQ has been replaced).
• In storage, the name of a file may be up to 37 characters long. This allows file names like e.g. 'Acornsoft.Snapper', where the 'Acornsoft.' part could be seen as a 'directory' (which you can 'enter' and 'exit' by using *Dir, if that is more convenient than simply using the full name).

File operations

GoSDC aims to be 'COS for flash cards'. No less, not much more.

What follows documents the expected file operations (for the additional ones, refer to File operations). Note that :

• A file name can never be empty (under COS it can be).
• Using FIN, FOUT or SHUT to open or close files is mandatory (under COS it is optional).
• You can simultaneously open one file for input and one file for output (under COS you must choose).

Refer to 'Atomic theory and practice' for detailed information about the file operations that are mentioned below.

*Save <name> <first> <final+1> (<exec>)
*Load <name> (<reload>)
*Run <name> (<reload>)
*Cat (<name>)
*Mon, *NoMon

These *-commands are all supported and work as usual, except :

• To show matching files only, *Cat may be followed by <name> (under COS it can not). Wildcards may be used, matching exactly one character (#) or a sequence of zero or more characters (*). See also *Info.
• Because they may be used in existing code, *Mon and *NoMon are accepted but do nothing (under COS they enable/disable tape recorder prompts).

SAVE, LOAD
FIN, FOUT, SHUT
GET, PUT, BGET, BPUT, SGET, SPUT, FGET, FPUT

These BASIC commands are all supported and work as usual.

OSSAVE, OSLOAD
OSFIND, OSSHUT
OSBGET, OSBPUT

These OS routines are all supported and work as usual.

Special use

Tool tasks

You run tools to execute a variety of tasks (if needed, refer to mainly the 'Basics' parts of Running tools).

What follows documents the less common tasks (for the more common tasks, refer to Tool tasks). Note that :

• 'Native' and 'Foreign' show the command line to enter if 'Suppose' is true (and the Q in -dQ has been replaced).
• In storage, every utility/extension has a number between 1 and 255 and every tool or file has a name up to 48 or 37 characters long, respectively.

SDCUP

This tool will update GoSDC's flash ROM (a 'firmware update').

A file named 'UPSDC' provides the actual data. To give SDCUP access to UPSDC, simply copy UPSDC to a GoSDC formatted flash card (with GoSDCio command 'ADD FILE UPSDC 0 0 UPSDC'), and then move the flash card to GoSDC.

After running SDCUP, always power-cycle the machine (switch it off, wait a few seconds, then switch it on again).

SDCA2A

This tool allows you to copy an entire area to another (relocating objects as required).

It is the only way to write to Area U. Numbered areas (on a flash card) can be written to as well, but should the source area contain more than a few MB of data, the copying will take a long time and is better done via GoSDCio (backup one area, restore to another).

Press digit keys to make choices from a menu (which will grow a bit along the way) :

• 0 exits SDCA2A.
• 1 allows selection of the area to copy from.
• 2 allows selection of the area to copy to.
• 3 (which appears once you did '1' and '2') will start the copy.

SDCCard

This tool will show interesting flash card details.

File operations

GoSDC aims to be 'COS for flash cards'. No less, not much more.

What follows documents the additional file operations (for the expected ones, refer to File operations).

*Delete <name>

Deletes the file named <name>.

The file is only marked as deleted. This means it will no longer be found, but still occupies storage space (until a backup and restore is performed with GoSDCio).

*Exec <name>

Will 'type' the characters in the file named <name> as if they were typed in at the keyboard.

*Info (<name>)

Lists the name, load address, execution address and size of all files matching <name> (or * if not specified). Wildcards may be used, matching exactly one character (#) or a sequence of zero or more characters (*). Addresses and sizes are displayed in hexadecimal. See also *Cat.

*Dir (<path>)

Changes the 'current directory' according to <path>. Refer to configuration variable DIRS for more details. The current directory is empty by default as well as after a CTRL-BREAK (pressing BREAK while holding CTRL).

The current directory (a.k.a. 'prefix') is what implicitly precedes all file names in *-commands, BASIC commands and OS routine calls. It can be used to simulate a 'directory structure'. Only if a file name starts with $, the prefix is ignored (and the $ is discarded). For example, if the current directory is 'One/Two/Three/', a SAVE or LOAD "Four" will actually save or load the file 'One/Two/Three/Four', an *Info with no argument will actually only list files whose name starts with 'One/Two/Three/', and a '*Run $Four' will actually run the file 'Four'.

ROM functions

GoSDC is your OS/BASIC ROM (IC20), and can be your utility or extension ROM (IC24 or IC21).

As an OS/BASIC ROM (address ranges #Cxxx and #Fxxx), GoSDC has three operating modes :

• Active mode. The ROM is original except for some code in the region between #FEFB and #FF3E that relays control to GoSDC when needed.
• Disabled mode. The ROM is 100% original, and GoSDC is 'gone'. Enter this mode by holding the 'G' and 'D' keys while powering up.
• Dormant mode. Is like active mode, but no vectors are claimed, so COS will be active by default. Enter this mode by holding the 'G' and 'D' keys while pressing BREAK. For example, to transfer a file from tape to flash card, enter dormant mode, load the file, enter active mode (by simply pressing BREAK), save the file.

As a utility or extension ROM (address range #Axxx or #Dxxx), GoSDC functions like an actual ROM would. Make sure you have 'the adapter' installed in the relevant ROM socket (refer to Installation for details) and configure GoSDC to auto-load the chosen ROM (refer to configuration variable UENR for details).

Area U

Area U is basically a user-definable area X.

It has limited storage capacity (normally a few hundred KB or so), but is always present. Especially if you want to add utility/extensions or your own tools, this eliminates the need to put them on all the flash cards you use.

Area U can only be written as a whole. Put its contents in a numbered area N (i.e. on a flash card), then use tool SDCA2A to copy area N to area U.

Reference

Parts and layers

Physically, GoSDC consists of several parts. The most important ones are :

• SD card slot

  This is where you insert your flash card.

• 1 MB flash ROM

  This contains the GoSDC ROM and supporting software.

• 32 KB static RAM

  This is divided into eight 4 KB parts : four where the GoSDC ROM runs (as four overlays), three where the OS ROM runs (a fully original Cxxx, a slightly changed Fxxx, a GoSDC dedicated Fxxx), one where the auto-loaded utility/extension resides.

• The adapter

  Installing the adapter allows you to auto-load a utility or extension ROM.

Logically, GoSDC consists of several layers. They are (starting at the 'bottom') :

• Storage

  Everything is stored either in the flash ROM or on the flash card.

• Areas

  All storage is divided into 'areas'. Only one area can be 'selected' at a time (the default is 1). The flash ROM contains areas X and U. The flash card contains areas 1 through 8 (depending on card capacity). All available flash card areas are 4 GiB, except the final one (e.g. a 10 GB card would contain areas 1 (4 GiB), 2 (4 GiB) and 3 (roughly 2 GB)).

• Objects

  All areas contain several 'objects'. These objects will be mostly files, but can also be utility/extensions or tools. Every time you use a file, only the currently selected area will be searched. Every time a utility/extension is auto-loaded or a tool is run, area X, then U, then the currently selected area will be searched. Area X contains all the standard utility/extensions and tools, so they are always available, regardless of which area is selected at the time.

• GoSDC ROM

  The GoSDC ROM allows utility/extensions to be auto-loaded, tools to be run, and files to be manipulated. It also provides tools with raw access to the currently selected area.

Running tools

There are two types of tool, 'native' and 'foreign'. Native tools run on your machine. Foreign tools run on a PC.

Native tools : Basics

On your machine, enter *SDCTool followed by the tool name and its arguments, e.g.

 *SDCTool SDCMOD AN myarea 

Note that all changes are made to the current area (as selected with *SDCArea, or 1 by default).

Foreign tools : Basics

On a PC, execute GoSDCio passing the flash card location and a command to execute, e.g.

 GoSDCio -dQ -c "ADD UE 1 fprom" 

Note that all changes are made to the specified area (as passed by option '-a', or 1 by default).

Your PC should be connected to a flash card reader, with your flash card inserted.

The following three operating systems are supported (skip to the one your PC uses) :

Windows (7 or later)

• To install GoSDCio

  Copy 'GoSDCio.exe' from this directory to a new directory.

  Note that you may also need to install Microsoft's 'Visual C++ Redistributable for Visual Studio 2017' (find it by googling the preceding quoted text).

• To execute GoSDCio

  Go to a command line environment (e.g. start 'Command Prompt'), 'cd' to the new directory, and enter  GoSDCio . GoSDCio should report itself (with a usage error).

• About what actually follows '-d' (where all examples show Q)

  Your flash card will appear as some drive (when you insert your flash card, you will probably get a 'not formatted' popup for that drive). Suppose the drive is 'P:', then your command line will always start with  GoSDCio -dP .

• To install GoSDCio

  Copy 'GoSDCio.unx' (x86) or 'GoSDCio.rpi' (arm) from this directory to a new directory, rename it to 'gosdcio', and ensure it has 'execute' permission.

• To execute GoSDCio

  Go to a command line environment (e.g. start a terminal), 'cd' to the new directory, and enter  ./gosdcio . GoSDCio should report itself (with a usage error).

• About what actually follows '-d' (where all examples show Q)

  Your flash card will appear as some file in the /dev/ directory (where exactly differs per setup). Suppose the path is '/dev/ppp', then your command line will always start with  ./gosdcio -d/dev/ppp .

• To install GoSDCio

  Copy 'GoSDCio.mac' from this directory to a new directory, rename it to 'gosdcio', and ensure it has 'execute' permission.

• To execute GoSDCio

  Go to a command line environment (e.g. start a terminal), 'cd' to the new directory, and enter  ./gosdcio  (preceded by 'sudo ' if needed). GoSDCio should report itself (with a usage error).

• About what actually follows '-d' (where all examples show Q)

  Your flash card will appear as some file in the /dev/ directory (where exactly differs per setup). Suppose the path is '/dev/ppp', then your command line will always start with  ./gosdcio -d/dev/ppp .

Foreign tools : Passing commands

GoSDCio executes any number of commands, in the order they were passed to it. Every command is either passed by option -c, or a line in a script.

A script is a text file that looks like this :

# start
ADD FILE ASTEROID 2900 3400 C:\GoSDC\GAMES01\ASTEROID
ADD FILE INVADERS 2900 CE86 C:\GoSDC\GAMES05\INVADERS
ADD FILE SNAPPER 2900 CE86 C:\GoSDC\GAMES09\SNAPPER
# end

There's one command per line. If a line is empty, or starts with a '#', it is ignored.

E.g., if a file 'myscript' contained the example script (see above), then

 GoSDCio -dQ -c "ADD FILE BREAKOUT 2900 CE86 C:\GoSDC\GAMES01\BREAKOUT" myscript 

would add BREAKOUT, ASTEROID, INVADERS and SNAPPER, in that order.

Note that order is rarely relevant, but may be in some cases (e.g. if multiple commands target the same object).

Foreign tools : Command line options

In addition to -d and -c (discussed here), the following GoSDCio command line options are available :

• -a<number>

  Use e.g. '-a2' to target area 2 (instead of area 1, the default). The range of <number> is 1 to 8.

• -f

  Use '-f' to empty the catalogue before any commands are executed. Emptying the catalogue is like running tool SDCFO, so use this option with extreme caution.

• -l

  Use '-l' to list the updated catalogue after all commands have been executed.

Star commands

GoSDC is primarily operated by executing 'star commands'.

Star commands can be issued from the command line and from BASIC. If a syntax error is detected, the correct syntax will be displayed (note that angle brackets enclose argument types, round brackets enclose what's optional, '|' means 'or' and '...' means unspecified text).

The commands are :

*SDCInfo

Displays the GoSDC software version and date, flash ROM and flash card details, and the sizes and names of all available areas.

*SDCArea (<selector>)

Selects area <selector> for subsequent access. If <selector> is not specified, no (new) area is selected.

In all cases the characteristics of the (newly) selected area are displayed (i.e. the total, used and free bytes, and the number of objects).

The areas you can select are X, U and 1 through 8 (refer to Parts and layers for details).

*SDCList (<name> (U)(T)(F)(O)(A) (X))

Lists all objects matching <name> (default '*'). Wildcards may be used, matching exactly one character (#) or a sequence of zero or more characters (*).

The second argument (default 'F') allows object type specification : any sequence of the characters U, T, F, O and A (standing for utility/extension, tool, file, other (not utility/extension, tool or file) and all respectively) lists those object types.

The third argument (no default) selects special listing styles : X selects 'extended' listing (showing 'tt ss aaaaaaaa + ssssssss name', all values hexadecimal, where tt is the object type, ss the object subtype, aaaaaaaa the start address on the flash card and ssssssss the size in bytes).

*SDCTool <name> ...

Runs tool <name>, relaying whatever follows <name>. Wildcards may be used, matching exactly one character (#) or a sequence of zero or more characters (*) (the first matching tool is run).

Tools run with *SDCTool are always copied to memory address #2900. Tools starting with an #0D byte are considered to be BASIC programs, and are executed by auto-entering '?#12=#29<CR>OLD<CR>RUN<CR>'. All other tools are considered to be machine code utilities, and are executed by calling #2900 after poking a 2-byte pointer to the command line tail to ?#2903 (low byte) and ?#2904 (high byte) (so there better be, e.g., a JMP #2905 at #2900).

Note that, if you want to run a non-standard tool, i.e. one that is not present in 'Area X', it must be present in 'Area U' or on the flash card (put there by you with a tool).

*SDCConfig (<name> <value>)

Changes the value of configuration variable <name> to <value>, or (with no arguments) lists all configuration variables. Refer to Configuration variables for details.

Configuration variables

GoSDC can be tweaked by changing 'configuration variables'.

Configuration variables have a name (of four characters) and a value (between 0 and 255) and can be changed through *SDCConfig. After a GoSDC software update (with tool SDCUP) or holding the 'G' and 'W' keys on power up, all values are reset to 0, which configures default behaviour.

The variables are :

UENR

This variable controls the utility/extension auto-load function. With this, a utility/extension can be automatically loaded into the 4 KB of RAM reserved for it (refer to Rom functions for details). This will occur on every power up.

Note that, if you auto-load a non-standard utility/extension, i.e. one that is not present in 'Area X', it must be present in 'Area U' or on the flash card (put there by you with a tool).

(1) Currently, only the Acorn FP extension ROM is in area X (as UE number 1).

DIRS

This variable selects what syntax *Dir uses to interpret paths.

The 'current directory' is a sequence of 'subdirectory' names separated by 'directory separator' characters (for example, 'One/Two/Three' has three subdirectories and uses '/' as the directory separator).

When a *Dir command is executed, the current directory (as set by previous *Dir commands) changes : subdirectories are taken off the end, then subdirectories are appended to the end. The *Dir argument determines what is taken off and what is appended.

The *Dir argument consists of an optional 'root directory' character, which takes off all subdirectories, followed by zero or more 'parent directory' sequences, which take off one subdirectory each, followed by what is to be appended. Like the current directory, all parts of the argument are separated by directory separator characters.

Note that 'Flat' is non-hierarchical : it always replaces everything. The others are hierarchical, and always ensure that the new current directory, if it's not empty, ends in a directory separator character.

Examples :

BOOT

This variable selects a boot activity, which is performed on every power up or BREAK (if you press SHIFT at the same time).

Note that the '$' causes the 'current directory' to be ignored, so it cannot affect the boot activity (refer to the discussion of *Dir for details).

WPRO

This variable configures flash card write-protection.

(1) Only if the SD or SDHC card is physically 'write protected', via the 'Lock' switch.

HACK

You should generally leave this at 0.

It contains eight 'hack bits', which, when set, enable certain drastic changes in the behaviour of the GoSDC ROM. To set bit 0, 1, 2, 3, 4, 5, 6 or 7 in the value, add 1, 2, 4, 8, 16, 32, 64 or 128 to it, respectively.

(1) Bypasses the SD/SDHC initialisation/detection code, which may confuse some very old MMCs.

Error messages

The GoSDC ROM issues the following errors :

• 'Escape' (code 17)

  Escape was pressed during *SDCList.

• 'File not found' (code 94)

  The file with the specified name does not exist.

• 'No room in area' (code 104)

  The current area lacks the free space to create the file.

• 'Syntax error: <correct syntax>' (code 135)

  A syntax error has been found in a *-command.

• 'Unknown variable' (code 135)

  The name specified to *SDCConfig is not recognized.

• 'Bad path syntax' (code 135)

  The path specified to *Dir does not adhere to the selected syntax.

• 'Directory too long' (code 135)

  The path specified to *Dir would make the current directory longer than 31 characters.

• 'Flash card is read only' (code 179)

  An attempt was made to write to the flash card while it was write-protected.

• 'Cannot write to a ROM area' (code 179)

  An attempt was made to write to 'Area X' or 'Area U'. They cannot be written to at all (X) or not directly (U).

• 'File input only' (code 193)

  Attempt to output to a file that is input only.

• 'File output only' (code 193)

  Attempt to input from a file that is output only.

• 'File is open' (code 194)

  The file being deleted, loaded, saved or opened is (already) open.

• 'Too many open' (code 194)

  Attempt to open two files for input or output (one each).

• 'File not open' (code 222)

  Attempt to read from or write to a file that is not open.

• 'End of file' (code 223)

  Attempt to read beyond a file's extent.

• 'File too big' (code 223)

  Attempt to write beyond a file's allocation.

• 'File not available' (code 254)

  This is an internal error (it should never occur).

• 'Access outside file' (code 254)

  This is an internal error (it should never occur).

• 'Failed to create file' (code 254)

  This is an internal error (it should never occur).

• 'GoSDC : No flash card inserted'

  The flash card socket indicates that no flash card is inserted.

• 'GoSDC : Flash card doesn't respond'

  The flash card doesn't seem to be present (although it is detected physically).

• 'GoSDC : Flash ROM doesn't respond'

  The flash ROM doesn't seem to be present (which should never, ever happen).

• 'GoSDC : Cannot find auto-load UE'

  You are trying to auto-load a utility/extension that cannot be found (i.e. is not in area X, U or 1).

• 'GoSDC : Configuration reset !'

  The 'G' and 'W' keys were held on power up. Refer to What is remembered for more information.

How to recover

If the contents of the GoSDC flash ROM have become corrupted, your machine may hang on power up, and recovery may seem impossible.

Fear not. This problem has been foreseen. GoSDC can be switched to a secondary copy of the software (which is never erased or updated). Switch to the secondary copy, use tool SDCUP (refer to its discussion for details), then switch back to the primary copy.

Follow the following recipe :

1) Power down.

2) Move the 'software select' jumper on GoSDC's configuration header (refer to the Installation section for details) to pins 2+4.

3) Power up.

4) Run SDCUP.

5) Power down.

6) Move the 'software select' jumper on GoSDC's configuration header back to pins 4+6.

7) Power up.

What is remembered

Choices made through *SDCConfig are stored in non-volatile memory, so they are remembered even when the machine is powered off. After a GoSDC software update (with tool SDCUP) or holding the 'G' and 'W' keys on power up, they are forgotten again.