GoSDC-Atom Guide

# Use | ## ↖

## Index

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

* Note that, when you first begin using GoSDC, it's recommended to limit yourself to these sections.

## 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 99 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).

Task | Format flash card
Notes | Insert the flash card, then press BREAK, then run this tool, then press BREAK again. Note that all data previously stored on the flash card will be lost.
Native | *SDCTool SDCFO

Task | Add a file
Suppose | Source file name is 'somefile'. New file name is 'humpty' and load / execution address is 0x12AB / 0x34CD.
Foreign | GoSDCio -dQ -c "ADD FILE humpty 12AB 34CD somefile"
Variations | If the source file is an 'ATM' file, specify '-' as both the load and execution address (to adopt the values in the ATM header and discard the header). It is optional to specify '-' as the new file name (to adopt the name registered in the ATM header).

### 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> ...
*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.
- The second argument of *Run is not a reload address (as in Atom COS), but a free-form string that is copied to #0100 onwards (as in Atom DOS). In addition, if '*<name>' is an unknown *-command but <name> exists as a file, this is interpreted as '*Run <name>'.
- 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.

Task | Add a tool
Notes | The source is a file. For structural details, refer to the discussion of *SDCTool. Add tools to the flash card if you want to run your own utilities and use *SDCTool to start them.
Suppose | Source file name is 'somefile'. New tool name is 'humpty'.
Foreign | GoSDCio -dQ -c "ADD TOOL humpty somefile"
Variations | Use a name that does not clash with names of tools that are stored in another area (in general, avoid names that start with 'SDC').

Task | Add a utility/extension
Notes | The source is a file. The file contains a 4 KB ROM image. Add utility/extensions to the flash card if you want to auto-load them.
Suppose | Source file name is 'somefile'. New utility/extension number is 200.
Foreign | GoSDCio -dQ -c "ADD UE 200 somefile"
Variations | Use a number that does not clash with numbers of utility/extensions that are stored in another area (you can use your own numbering system).

Task | Delete an object
Notes | The object is 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).
Suppose | The object is utility/extension 200.
Foreign | GoSDCio -dQ -c "DELETE UE 200"
Suppose | The object is tool 'humpty'.
Foreign | GoSDCio -dQ -c "DELETE TOOL humpty"
Suppose | The object is file 'humpty'.
Foreign | GoSDCio -dQ -c "DELETE FILE humpty"

Task | Rename an object
Notes | The object name is changed.
Suppose | The object is tool 'humpty'. New name is 'dumpty'.
Foreign | GoSDCio -dQ -c "RENAME TOOL humpty dumpty"
Suppose | The object is file 'humpty'. New name is 'dumpty'.
Foreign | GoSDCio -dQ -c "RENAME FILE humpty dumpty"

Task | Extract an object
Notes | The object is copied to a file.
Suppose | The object is utility/extension 200. Target file name is 'somefile'.
Foreign | GoSDCio -dQ -c "EXTRACT UE 200 somefile"
Suppose | The object is tool 'humpty'. Target file name is 'somefile'.
Foreign | GoSDCio -dQ -c "EXTRACT TOOL humpty somefile"
Suppose | The object is file 'humpty'. Target file name is 'somefile'.
Foreign | GoSDCio -dQ -c "EXTRACT FILE humpty somefile"

Task | Create a new, empty file
Notes | If, Atom side, you want a file to grow beyond 256 KB (which is the default limit), you can use NEW (instead of ADD-ing a large, pre-existing file).
Suppose | New file's size limit is 16 MB. New file name is 'humpty'.
Foreign | GoSDCio -dQ -c "NEW FILE humpty 16M"

Task | Modify flash card
Notes | Makes (subtle) modifications to the flash card. Currently, only one modification is available (more may follow).
Suppose | You want to name an area (*SDCInfo will then reflect this). The area is currently selected. The name is 'humpty'.
Native | *SDCTool SDCMOD AN humpty

Task | Backup and restore
Notes | Backup copies everything that is stored on the flash card to a directory, as a bunch of files and a 'restore' script (discarding everything that was deleted). Restore is accomplished by executing the script from the backup directory.
Suppose | You're doing a backup. Target directory name is 'somedir'.
Foreign | GoSDCio -dQ -c "BACKUP somedir"
Suppose | You're doing a restore. You did a 'cd' to the backup directory.
Foreign | GoSDCio -dQ -f script

Task | Update the software
Notes | Refer to 'SDCUP', below.
Native | *SDCTool SDCUP

Task | Copy area to area
Notes | Refer to 'SDCA2A', below.
Native | *SDCTool SDCA2A

Task | Show flash card details
Notes | Refer to 'SDCCard', below.
Native | *SDCTool SDCCard

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). Area numbers are limited to 1 through 9 (not 99).

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'.

PTR, EXT

These BASIC keywords are all supported and work as usual.

For details, you can refer to 'Atomic theory and practice' as well as the documentation for the 'Atom Disc Pack'.

OSRDAR, OSSTAR

These OS routines are all supported and work as usual.

For details, you can refer to 'Acorn System DOS Technical Manual' ('Atomic theory and practice' does mention but does not document these calls).

### 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 a different filing system is in control (and claiming the vectors). Refer to Filing system switch for details. This can be used, for example, to transfer a file from tape to flash card : switch to COS, load the file, switch back to GoSDC, 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). (PRO differs)

### 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.

### Filing system switch

The filing system switch function of GoSDC allows you to easily switch between filing systems.

To enable switching, set configuration variable FSUE to a non zero value. Once enabled, holding a specific key pair on reset (i.e. power up or BREAK) will perform a switch, which will stick until the next switch, or power off. If needed, the relevant filing system ROM (UE) will be auto-loaded, and called every reset.

The following filing systems are supported :

Key 1 | Key 2 | Filing system | UE number | UE address | Called at
--- | --- | --- | --- | --- | ---
G | - | GoSDC | - | - | -
C | - | COS | - | - | -
D | - | DOS | FSUE + 1 | #E000 | #E000
M | A | AtoMMC | FSUE + 2 | #A000 | #AFCC
M | E | AtoMMC | FSUE + 3 | #E000 | #E000
L | A | LFS | FSUE + 4 | #A000 | #A003
L | E | LFS | FSUE + 5 | #E000 | #E003

For example, if FSUE is set to 100, and UE 101 is present, then holding D and - while pressing BREAK will switch to DOS (loading UE 101 when switching, and calling #E000 every reset). Switch back to GoSDC by holding G and - while pressing BREAK.

### PRO perks

The PRO version of GoSDC-Atom adds 'ROM/RAM board' and 'turbo' functions :

Enable extra RAM

To enable extra RAM, change the value of configuration variable RAME, then power-cycle the machine.

The value contains four bits. Setting a bit enables RAM in specific parts of the memory map. To set bit 0, 1, 2 or 3 in the value, add 1, 2, 4 or 8 to it, respectively.

Bit | RAM enabled at | Description
--- | --- | ---
0 | #2800 - #3BFF | A.k.a. 'internal RAM'. Replaces IC10 through IC19. Note : any chips in the mentioned sockets must be removed !
1 | #0400 - #27FF, #3C00 - #7FFF | A.k.a. 'external RAM'. Note : IC4 must be removed (and expansions cannot be used) !
2 | #A000 - #AFFF, #D000 - #DFFF | A.k.a. 'internal ROM'. Replaces IC21 and IC24. Note : any chips in the mentioned sockets must be removed !
3 | #E000 - #EFFF | A.k.a. 'external ROM'. Note : IC4 must be removed (and expansions cannot be used) !
others |  | reserved

Additionally, if IC51 and IC52 are missing, RAM will be enabled at #0000 - #03FF. This happens automatically.

For example, if your Atom has the maximum 12 KB RAM (#0000 - #03FF, #2800 - #3BFF and #8000 - #97FF), then changing RAME to 2 will increase that to 38 KB (#0000 - #97FF).

The utility of replacing RAM that is already there (i.e. IC51, IC52, IC10 - IC19) may not be immediately apparent, but GoSDC RAM is fast enough to operate at (e.g.) 4 MHz, whereas the replaced RAM most likely is not. See also 'Speeding up'.

Write-protect ROM

RAM above #8000 can be write-protected. Simply write #81 or #80 to #BFFF to disable or enable writes, respectively.

#Axxx banking

There are eight banks of RAM at #Axxx (32 KB total). Simply write a bank number (0-7) to #BFFF to select that bank.

Speeding up

Either the motherboard or GoSDC can provide the 6502's clock signal, if the jumper just 'north' of GoSDC's 6502 socket is set 'east' or 'west' respectively.

To select GoSDC's clock frequency, change the value of configuration variable CLKS, then power-cycle the machine.

CLKS | Clock frequency
--- | ---
0 | 1.00 MHz
1 | 2.00 MHz
2 | 3.33 MHz
3 | 4.00 MHz
others | reserved

Your machine will only be able to run at clock frequencies above 1 MHz if certain components (in particular : 6502, 8255, any RAM or ROM) are up to it. To run at 4 MHz, it is recommended to use a UM6502C, D8255AC-2, fast enough video RAM (at #8000 - #97FF) and otherwise only GoSDC RAM.

## 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. (PRO differs)

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 99 (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 .

Linux (x86/arm versions)

- 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 .

macOS (x86 versions)

- 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 99.

- -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 :

Name | Description
--- | ---
SDCInfo | displays system information
SDCArea | selects the current area
SDCList | lists stored objects
SDCTool | executes tools
SDCConfig | changes configuration variables

*SDCInfo

Displays the GoSDC software version and date, detected UE slots, flash ROM and flash card details, and the sizes and names of all formatted 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 99 (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 :

Name | Description
--- | ---
UENR | sets the number of the utility/extension to auto-load
DIRS | selects the syntax of paths interpreted by *Dir
BOOT | selects the activity to perform on booting
WPRO | selects the flash card write protection level
FSUE | sets the base number of filing system UEs
HACK | should be left alone in normal circumstances

UENR (PRO differs)

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.

UENR | Auto-load what
--- | ---
0 | nothing
1 | utility/extension 1 (1)
2 | utility/extension 2
... | ...
255 | utility/extension 255

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.

DIRS | Syntax
--- | ---
0 | Flat
1 | Unix
2 | Windows
3 | Risc OS
others | reserved

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.

Syntax | Root directory | Parent directory | Directory separator
--- | --- | --- | ---
Flat | Implied | Does not exist | Does not exist
Unix | / | .. | /
Windows | \ | .. | \
Risc OS | $ | ^ | .

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 :

Syntax | CD (old) | *Dir Argument | CD (new)
--- | --- | --- | ---
Flat | OneTwoThree | FourFiveSix | FourFiveSix
Unix | One/Two/Three/ | /Four/Five/Six | Four/Five/Six/
Windows | One\Two\Three\ | ..\..\Four | One\Four\
Risc OS | One.Two.Three. | ^ | One.Two.

BOOT

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

BOOT | Activity
--- | ---
0 | none
1 | auto-enter '*EXEC $!BOOT'
2 | auto-enter '*RUN $!BOOT'
others | reserved

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.

WPRO | Writing is
--- | ---
0 | passed
1 | silently ignored
2 | faulted with an error
3 | silently ignored (1)
4 | faulted with an error (1)
others | reserved

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

FSUE

This variable both enables and configures the filing system switch (if its value is non zero).

Refer to Filing system switch for details.

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.

Bit | Effect when set
--- | ---
0 | MMC only mode (1)
others | reserved

(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).

The GoSDC ROM shows the following alerts (after reset, at the top of the screen) :

- '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.

- 'GoSDC : enabled RAM reduced' (PRO only)

  RAM can only be enabled if specific on-board ICs are absent. One or more violations were detected, and, to prevent hardware issues, the relevant RAM was not enabled. See configuration variable RAME. Note : if you want violations to be ignored (and accept the risks of doing so), you can add 128 to the value of RAME.

### 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.

(PRO differs) The PRO version of GoSDC-Atom allows you to auto-load three UEs (by enabling RAM at #Axxx, #Dxxx and #Exxx, and using configuration variables UEAR, UEDR and UEER, respectively). The OSR version of GoSDC-Atom allows you to auto-load one UE (by installing the adapter, and using configuration variable UENR). See also PRO perks.