Use

Index

• Overview
• Terminology
• Quick start *
• General use *
  • Fundamentals
  • Tool tasks
• Special use
  • Tool tasks
  • Tapes
  • Second processors
  • Area U
• Reference
  • Parts and layers
  • Filing systems
  • Disc images
  • Sideways ROM/RAM
  • Running tools
  • Star commands
  • Configuration variables
  • Error messages
  • How to recover
  • What is remembered

Overview

GoSDC is a storage system for the Acorn BBC (B, B+, Master) and Electron.

It allows you to store virtually any number of discs on a single flash card, and use them via familiar filing systems, with increased convenience and speed. Supported flash card types are MMC, SD, SDHC and SDXC. Discs may be DFS or ADFS format, may be sourced from real floppy discs, real hard discs or disc image files, or may be created. There's also support for tapes (read only).

GoSDC is self-contained, and can make do with a completely 'bare' machine (without disc interface or other upgrades).

Terminology

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

Also, in case you're not yet familiar with the term, a filing system is a software layer between user (you) and storage medium (e.g. floppy disc or hard disc). Refer to Filing systems for more information. This guide is not a filing system tutorial (if you need one, you can find relevant DFS and ADFS manuals and tutorials on the Internet).

Quick start

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

• Run a patched DFS
  • Reset the configuration
    • Hold the 'G' and 'W' keys while powering up your machine.
    • 'GoSDC : Configuration reset !' should be displayed.
  • Let SDCLead do the rest
    • 1. Hold the 'D' key while powering up your machine.
    • 2. Enter  *SDCTool SDCLead .
    • 3. Choose 1 (Run patched DFS), and follow the advice.
    • Repeat steps 1, 2, 3 until 'You have reached your goal'.
    • Optionally, read Filing systems (to understand SDCLead).
• Format a flash card
  • Pick a flash card, insert it into GoSDC's card slot and press CTRL-BREAK.
  • Note that any existing flash card contents will be lost after the next step !
  • Enter  *SDCTool SDCFO  and press CTRL-BREAK after.
  • Optionally, enter  *SDCInfo  and read Parts and layers.
• Create a DFS disc
  • Enter  *SDCTool SDCNEW D 400K quicky .
• Save and load a file
  • Enter  *SDCDisc quicky  and press CTRL-BREAK after.
  • Enter  10 REPEAT PRINT "Hello":UNTIL FALSE .
  • Enter  SAVE "hello"  and then  CHAIN "hello" .

Congratulations. You have created a disc, and saved a file to it.

That was a simple example. GoSDC gives you many degrees of freedom. You can use DFS, or ADFS, or both. You can have any number of discs (limited only by the flash card capacity), each with their own name and size (limited only by the filing system : 400 KB for DFS, 512 MB for ADFS). You can add discs from a variety of sources, or create new ones.

General use

Fundamentals

Operating GoSDC fundamentally involves :

• Run a patched filing system

  You will generally do this only once. A patched filing system (an original filing system changed to interface with GoSDC instead of a disc drive) needs to run on your machine. Choose one, and configure GoSDC to auto-load it. For a guided example, follow the Quick start. For detailed information, refer to Filing systems.

• Format the flash card

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

• Add discs to the flash card

  You will tend to do this occasionally. Refer to Tool tasks for instructions.

• Use discs on the flash card

  You will likely do this all the time. Use *SDCDisc to select a disc, press CTRL-BREAK, and use the disc.

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 CTRL-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 disc may be up to 48 characters long. This allows disc names like e.g. 'Acornsoft.Hopper', where the 'Acornsoft.' part could be seen as a 'directory' (which you can 'enter' and 'exit' by using *SDCPrefix).
• The internal structure of ADFS 'floppy discs' (<= 640 KB) and 'hard discs' (> 640 KB) is identical. The distinction is only made by an 'original' ADFS, and only because the two are on different hardware interfaces.

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 filing system has a number between 1 and 255 and every tool or medium (disc or tape) has a name up to 48 characters long.

SDCMenu

This tool allows you to easily locate a disc or tape (and then select it).

Enter any part of the name (using the left and right arrow keys to move around, DELETE to remove a character, SPACE to reset to nothing). Then press RETURN to search. All matches that '*SDCList *blah*' would have brought up (if what you entered is 'blah') will be listed. Choose a match by pressing the key indicated in front of it, or press RETURN to go back to the name prompt. If there are more matches than will fit on screen, the list will end with '...'. Then either enter a bit more of the name, or choose a match anyway.

Choosing a match will execute an *SDCDisc or *SDCTape command, as appropriate, and exit SDCMenu. If you selected a disc, then, assuming a patched filing system is running, subsequently pressing CTRL-SHIFT-BREAK should boot the selected disc. If you selected a tape, enter '*Tape', then 'CHAIN""' or '*Run' as appropriate.

Ideally, SDCMenu is run automatically, by setting configuration variable BOOT to 3. You press CTRL-BREAK to run SDCMenu, then select a disc, then press CTRL-SHIFT-BREAK to boot the selected disc (SDCMenu won't be run this time, because the BOOT setting is ignored when SHIFT is pressed).

SDCHelp

This tool allows you to build a native tool command (in an interactive way).

Simply answer the questions until the appropriate command line is quoted.

SDCFlop

This tool allows you to copy a disc (back) to a real floppy.

Ensure that the original filing system needed to write to your floppy is running (refer to Filing systems if needed).

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

• 0 exits SDCFlop.
• 1 allows you to switch between DFS and ADFS. When you switch, your previous choices are assumed to not apply anymore, and you will revert to the basic startup menu.
• 2 allows selection of the drive (on your real floppy) to copy to.
• 3 allows selection of the disc (on the flash card) to copy from. You may use wildcards.
• 4 (which appears once you did '3') allows selection of the drive to copy from (i.e. a drive contained by the disc selected via '3'). Beware of selecting 'shrunk' drives, since they will leave part of your floppy's capacity unused, and won't allow files to be added later on.
• 5 (which appears once you did '2', '3' and '4') will start a drive copy.
• 6 (which appears once you did '2', '3' and '4') will start a drive verify.

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 the root directory of a FAT formatted flash card, and then move the flash card to GoSDC. E.g., on a PC running Windows, simply format your flash card via 'My Computer' (if needed), and then drag UPSDC to it.

Usually, a previous version of the GoSDC ROM will already be running on your machine. If so, GoSDC's ROM number will be determined automatically. If not, you will be asked for it.

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.

SDCLead

This tool will actively help to reach a goal. As used in Quick start.

Tapes

Besides discs, GoSDC supports tapes (read only).

Using tapes via GoSDC involves the following :

• Replace your OS ROM

  The tape filing system has to interface with GoSDC. You can arrange this by replacing your machine's original OS ROM with a patched one (i.e. a PROM with the patched version of the OS programmed into it). You can find the patched OS ROM image in this directory :

  • POS120.BIN is the (16K) BBC model B OS 1.20 ROM
  • POS320.BIN is the (128K) BBC Master MOS 3.20 ROM
  • POS350.BIN is the (128K) BBC Master MOS 3.50 ROM
  • POS100.BIN is the (32K) Electron OS 1.00 ROM (i.e. this includes BASIC)
  • POS200.BIN is the (32K) BBC B+ OS 2.00 ROM (i.e. this includes BASIC)

  Note that replacing the OS ROM is not for the fainthearted. Only on the BBC model B and B+ it is fairly easy to do.

• Add tapes to the flash card

  Use GoSDCio's 'ADD TAPE' command. The source file must be an 'ungzipped' UEF file. Note that if you download these files from the Internet, you may have to 'unzip' (to obtain the compressed UEF file) as well as 'ungzip' (to uncompress it).

• Use tapes on the flash card

  The tape filing system must be active (e.g. enter  *Tape ). Use *SDCTape to select a tape. Enter  CHAIN""  or  *RUN  (as appropriate) to start loading. Use *SDCRewind to 'rewind' (but note that *SDCTape rewinds as well). Use configuration variable SLOW to make the tape loading speed more 'realistic'.

Second processors

GoSDC fully supports second processors. In fact, it goes beyond in the following ways :

• More speed

  Originally, DFS and ADFS use 1-byte Tube transfers only, but since their patched versions leave data transfer to GoSDC, you have the option to select 2-byte or even faster (via configuration variable TUBE).

• Compatibility

  When you're using a 32016 Second Processor, you can tell GoSDC (via configuration variable COPR). This solves known potential issues with Tube transfers, for all supported filing systems.

For more details, refer to the discussion of the relevant configuration variables.

Area U

Area U is basically a user-definable area X.

It has limited storage capacity (normally half a megabyte or so), but is always present. Especially if you want to add your own filing systems or 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 two 16 KB banks : one where the GoSDC ROM runs, one where the 'free ROM bank' resides. The free ROM bank is like a sideways RAM bank, but cannot be written to directly.

• The adapter

  The free ROM bank is only available when GoSDC has access to two sideways ROM banks. This is true if GoSDC is plugged into a '32K' socket, or if both GoSDC and the adapter are plugged into '16K' sockets.

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 discs, but can also be filing systems or tools. Every time you select a disc, only the currently selected area will be searched. Every time a filing system 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 filing systems and tools, so they are always available, regardless of which area is selected at the time.

• GoSDC ROM

  The GoSDC ROM allows filing systems to be auto-loaded, tools to be run, and discs to be selected. It also provides patched filing systems with raw access to the currently selected disc(s) and provides tools with raw access to the currently selected area.

• Patched filing systems

  Patched filing systems interface with the GoSDC ROM to allow user access to the currently selected disc(s).

Filing systems

Filing systems allow users to store and manipulate files (e.g. save, load, delete) on some storage medium (e.g. floppy disc). GoSDC supports a specific set of filing systems. For a list, see below.

Supported filing systems can be 'patched' or 'original'. The patched version of a filing system can access discs on the flash card. The original version of a filing system can be used in the process of copying 'real' discs to the flash card (which can then be used via the patched version).

A filing system can be run by configuring GoSDC to auto-load it into a sideways RAM bank (transparently, on every power up), or in exceptional cases by programming the filing system image into a PROM and plugging that into a sideways ROM socket. To auto-load, use configuration variables FSNR and FSRM. For the PROM way, you can find the filing system image in this directory ('O' = original, 'P' = patched, 'D' = DFS, 'A' = ADFS, version number : see the list below).

Supported filing systems are of either DFS or ADFS type. At any one time, you should not run more than one of each type. Whenever there can be two (e.g. if you auto-load a patched DFS but you also have a DFS ROM in your machine for your disc interface), you must 'unplug' one and 'insert' the other. To unplug and insert, use *SDCSPlug operations 1 and 0 (or *Unplug and *Insert on a BBC Master).

Only one filing system is active on your machine at any one time. Which one is active by default is determined by a key held during power up, or by sideways ROM priority. If you hold a specific key during power up, only a filing system of a specific type will become active (if one is present). Hold 'D' for DFS, or either 'A' or 'F' for ADFS (A will attempt a disc mount, F will not). If no key is held during power up, the filing system with the highest ROM number (15 down to 0) will become active. If no filing system became active, the default filing system (usually the tape filing system) will. Note that you can also switch between filing systems by entering their selection commands (e.g. *DISC for DFS, *ADFS for ADFS, *LFS for LFS). The BBC Master MOS also allows a temporary switch in some commands (e.g. '*LOAD -lfs-myfile' with DFS active would switch to LFS, load 'myfile', and switch back to DFS).

The following filing systems are supported :

The number is the GoSDC 'internal' filing system number, i.e. it is the appropriate value for configuration variable FSNR and is listed as the subtype of filing system objects in an 'extended' *SDCList. Note that numbers 81 and higher may be used as well (these are the original, unpatched versions of the patched filing systems whose number is 80 less).

(1) Note that DFS 2.45 and ADFS 2.03 are co-dependent (they share routines) and need to be in the machine at the same time, one as an even numbered ROM x, the other as ROM number x + 1. Use configuration variables FSNR/FSRM to auto-load one, and F2NR/F2RM to auto-load the other. On the BBC Master, you would normally use sideways RAM banks 4 and 5.

(2) Note that these are 'E00' filing systems (they leave the default PAGE in an unexpanded machine at &0E00), and have to run in a sideways RAM bank (note that the free ROM bank on GoSDC is not suitable, since it cannot be written to directly).

(3) Note that this allocation is versionless (all versions of HADFS are detected as, and considered to be, the same filing system), and that HADFS contains its own GoSDC driver code (i.e. no 'original' version of the filing system, whose number would be 92, is considered to exist).

Disc images

A disc image is a copy of the contents of a 'real' disc (floppy or hard).

A 'real' disc has a number of surfaces (e.g. a single sided floppy disc has one, a double sided floppy disc has two). A disc drive reads or writes the disc with a 'head', one per surface. Every surface is divided into a number of 'tracks'. Every track is divided into a number of 'sectors'.

Usually, when a 'real' disc is 'imaged', the disc image is written sequentially, but the tracks on the 'real' disc can be read in two different orders : 'all heads per track' a.k.a. 'interlaced' (track N, all heads, track N+1) or 'all tracks per head' a.k.a. 'non-interlaced' (head N, all tracks, head N+1). Note that if there's just one surface, there's no difference between the two.

Disc images on the flash card are always non-interlaced. So, if you're performing a transfer to or from an interlaced disc image file, a conversion needs to take place, from interlaced to non-interlaced or vice versa. The relevant tool will give you a choice between 'N' (non-interlaced) or 'I' (interlaced).

For disc images you download from the Internet, non-interlaced is the norm. 'SSD' or 'Single Sided Disc' images are never interlaced. 'DSD' or 'Double Sided Disc' images are likely to be interlaced. Hard disc images are probably never interlaced.

Sideways ROM/RAM

Different machines have different sideways ROM/RAM systems :

The BBC model B

The standard machine has four sideways ROM sockets (all 16 KB), and no sideways RAM.

Starting at the ROM socket that is closest to the side of the machine, going 'west', the ROM numbers represented by the sockets are : 15, 14, 13, 12.

Only if you installed GoSDC 'with adapter' (refer to the Installation section of this manual for details) you can use the free ROM bank on GoSDC. This should be seen as a sideways ROM bank, but can still be auto-loaded into (via configuration variable FSRM). To find out its number, enter '*SDCInfo', and note the number of the 'free' ROM slot.

The BBC Master

The standard machine has three sideways ROM sockets (two 32 KB, one 16 KB), and four sideways RAM banks. Although not all at the same time, see below.

Starting at the ROM socket that is closest to the cartridge connector(s), going 'north', the ROM numbers represented by the sockets are : 4+5, 8, 6+7. I.e. the sockets for ROM numbers 4+5 and 6+7 are the 32 KB sockets. Whether ROM numbers 4+5 or 6+7 are sideways ROM banks (i.e. reflect what is in the ROM socket) or sideways RAM banks (what is in the ROM socket is irrelevant) is determined by links. If LK18 is set 'west', 4+5 is sideways RAM (or if 'east', ROM). If LK19 is set 'west', 6+7 is sideways RAM (or if 'east', ROM).

Usually, GoSDC is in the socket for ROM numbers 6+7, which means that the GoSDC ROM is ROM number 7, and ROM number 6 is the free ROM bank on GoSDC. This should be seen as a sideways ROM bank, but can still be auto-loaded into (via configuration variable FSRM).

The BBC B+

The standard machine has five sideways ROM sockets (all either 16 or 32 KB, selectable via links), and no sideways RAM.

ROM sockets IC35, IC44, IC57, IC62 and IC68 represent ROM numbers 2+3, 4+5, 6+7, 8+9 and 10+11 respectively, and links 9, 11, 12, 15 and 18 respectively determine whether they are 32 KB sockets (link set 'east') or 16 KB sockets (link set 'west').

If GoSDC is in the socket for ROM numbers x+y, then the GoSDC ROM is ROM number y, and ROM number x is the free ROM bank on GoSDC. This should be seen as a sideways ROM bank, but can still be auto-loaded into (via configuration variable FSRM).

The Electron

You are using an interface between GoSDC and Electron. There are three types :

• Elk2GoSDC (old type)

  This offers offers one of :

  a) No banks (no chip is installed in the utility socket)
  b) Up to 2 sideways ROM banks (28-pin ROM installed in the utility socket, e.g. a 27C256)
  c) Up to 2 sideways RAM banks (28-pin SRAM installed in the utility socket, e.g. a 62256)
  d) Up to 8 sideways ROM banks (32-pin ROM installed in the utility socket, e.g. a 27C1001)
  e) Up to 8 sideways RAM banks (32-pin SRAM installed in the utility socket, e.g. a 628128)

  Refer to the Installation section of this manual for further details, including how to install the chip.

  The ROM numbers are a little odd. For options b, c and f, the lower bank is 3 (and mirror images appear in 2, 1 and 0), and the higher bank is 13 (and mirror images appear in 12, 7 and 6). For options d and e, going from lower to higher addresses within the chip, the banks are 1, 13, 3, 7, 0, 12, 2, 6 (this is, of course, only relevant if you use a ROM, and need to know where to put the ROM images within the chip's address space).

• Elk2GoSDC (new type)

  This offers 8 sideways RAM banks. The ROM numbers are like option e for the old type.

• Cart2GoSDC

  This offers 2 sideways RAM banks. The ROM numbers are normally either 0+1 or 2+3.

GoSDC is in the socket for ROM numbers 15+14, which means that the GoSDC ROM is ROM number 15, and ROM number 14 is the free ROM bank on GoSDC. This should be seen as a sideways ROM bank, but can still be auto-loaded into (via configuration variable FSRM).

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 SDCNEW D 400K mydisc 

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 "NEW DFS DISC mydisc 400K" 

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 .

Native tools : Run as a file

There are two ways to run native tools :

• The normal way

  Via GoSDC, with *SDCTool.

• The alternative way

  Via a filing system, with *Run or CHAIN. This requires the filing system to have access to the file form of the tool (most are in this directory). You *Run SDCADI, SDCAFS, SDCATO, SDCCPY, SDCDEL, SDCFO, SDCMOD and SDCNEW. You CHAIN SDCA2A, SDCCard, SDCFlop, SDCHelp, SDCLead, SDCMenu and SDCUP. If you *Run, ensure that the file's load and execution addresses are set to &2000.

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 DFS DISC N Elite C:\GoSDC\Discs\Elite.ssd
ADD DFS DISC N Hopper C:\GoSDC\Discs\Hopper.ssd
ADD DFS DISC N Snapper C:\GoSDC\Discs\Snapper.ssd
# 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 "NEW DFS DISC mydisc 400K" myscript 

would 'NEW' mydisc, 'ADD' Elite, 'ADD' Hopper and 'ADD' 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 : Drive alterations

While adding discs, GoSDCio can perform on-the-fly alterations to all the drives contained within the disc image, using the following commands :

• DO COMPACT (undone by DO NOCOMPACT or DO NONE)

  will move all objects on a drive to the 'front' (exactly like the *Compact command).

• DO SHRINK (undone by DO NOSHRINK or DO NONE)

  is like DO COMPACT, but also minimizes the drive's size (i.e. no free space will remain).

• DO BLOWUP <size> (undone by DO NOBLOWUP or DO NONE)

  will enlarge a drive to the nearest size possible. A valid <size> is e.g. '200K' or '16M'.

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 most languages. Enter  *Help GoSDC  to list them all (noting 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, which ROM slots GoSDC occupies, 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).

ALWAYS press CTRL-BREAK after selecting an area with *SDCArea. It is highly recommended to enter '*SDCDisc -' as well, at this stage.

*SDCDisc (<name> (A|B|C|D))

Selects disc <name> for subsequent access (by the currently running, patched filing system). The usual * and # wildcards may be used (the first matching disc is selected). If <name> is a single hyphen (-), all disc selections are forgotten (this may occasionally be useful to acknowledge that what was selected is no longer on the flash card, although normally you would simply make new selections). If <name> is not specified, no (new) disc is selected.

The second argument is optional, and defaults to 'A'. It identifies the 'slot' (roughly equivalent to a real floppy or hard drive) that the disc is 'put into'. For DFS, slot A represents drives 0 and 2, slot B represents drives 1 and 3, and slots C and D represent an override for drive 2 and 3 respectively. For ADFS, slots A, B, C and D represent drive 0, 1, 4 and 5 respectively.

In all cases the (newly) selected discs are displayed, as well as the drives found within. DFS and ADFS disc selections are remembered separately.

ALWAYS press CTRL-BREAK after selecting a disc with *SDCDisc. GoSDC does not need this, but the patched filing system might, to notice the disc change.

*SDCTape (<name>)

Is like *SDCDisc, but selects a tape, Refer to Tapes for details.

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

Lists all objects matching <name> (default '*'). The usual * and # wildcards may be used.

The second argument (default 'M') allows object type specification : any sequence of the characters F, T, M, O and A (standing for filing system, tool, medium (disc or tape), other (not filing system, tool or medium) 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).

*SDCPrefix (<name>)

The 'name prefix' may be changed by this command. This affects *SDCDisc, *SDCTape, *SDCList and *SDCTool. The name prefix is what implicitly precedes the <name> specified in the affected commands. If <name> is a single hyphen (-), the name prefix is cleared (this is also the default). If <name> is not specified, no (new) name prefix is set.

In all cases the (new) name prefix is displayed.

E.g. suppose you have three discs, named 'Acornsoft.Hopper', 'Acornsoft.Elite' and 'Aardvark.Frak'. Setting the name prefix to 'Acornsoft.' (note the trailing dot !) would cause '*SDCDisc Hopper' to select the first disc, and '*SDCList *' to list the Acornsoft discs only (as if you had entered '*SDCDisc Acornsoft.Hopper', and '*SDCList Acornsoft.*').

Note that a leading '$' in the name specified to *SDCDisc, *SDCTape, *SDCList and *SDCTool will skip the matching of the name prefix (and the '$' is discarded). E.g. if the prefix is 'A.', then the name '$!Boot' matches '!Boot' only, not 'A.!Boot'.

*SDCTool <name> ...

Runs tool <name>, relaying whatever follows <name>. The usual * and # wildcards may be used (the first matching tool is run).

Tools run with *SDCTool are always copied to memory address &2000. Tools starting with an &0D byte are considered to be BASIC programs, and are executed by inserting 'PAGE=&2000<CR>OLD<CR>RUN<CR>' into the keyboard buffer. All other tools are considered to be machine code utilities, and are executed by calling &2000 after poking a 2-byte pointer to the command line tail to ?&2003 (low byte) and ?&2004 (high byte) (so there better be, e.g., a JMP &2005 at &2000).

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

Also note that you can auto-execute an *SDCTool command on every BREAK by using configuration variable BOOT.

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

*SDCSPlug <slot> <oper>

Configures 'plug' operation <oper> (0 through 2) for ROM number <slot> (0 through 15).

Plug operation 0 means 'nothing' (and is the default for all ROMs), 1 means 'unplug', 2 means 'reinsert'. You can read about the main use case for 'unplug' in Filing systems. You can use 'reinsert' if the OS automatically 'unplugs' the specified ROM because it looks like an alias of another ROM (but isn't).

Always press CTRL-BREAK after using *SDCSPlug. Note that the GoSDC ROM should have the highest possible ROM number in the machine, since it can only reliably affect the 'plug' state of ROMs with lower ROM numbers. Note that on the BBC Master, *Unplug and *Insert can be used instead of plug operations 1 and 0, respectively.

*SDCReset

Simulates a power up reset. Use this in preference to a power-cycle (switching power off, then on again).

*SDCRewind

This 'rewinds' the currently selected tape. See also '*SDCTape'.

*SDCSLoad <slot> <file>

Copy file <file> to ROM slot <slot>.

Note that this uses memory locations &0A00 through &0AFF as a temporary buffer. This means that you cannot use RS423 or cassette input while using this command.

*SDCSSave <slot> <file>

Copy ROM slot <slot> to file <file>.

Note that this uses memory locations &0A00 through &0AFF as a temporary buffer. This means that you cannot use RS423 or cassette input while using this command.

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 :

FSNR and FSRM (F2NR and F2RM for a second filing system, if any)

These variables control the filing system auto-load function. With this, a filing system can be automatically loaded, into either a sideways RAM bank, or the free ROM bank on GoSDC. This will occur on every power up.

A sideways RAM bank must be writable simply by selecting it, which is true for most sideways RAM upgrades for the BBC B/B+, the BBC Master sideways RAM system, and the sideways RAM on the interface between GoSDC and Electron. Refer to Sideways ROM/RAM for more details specific to your machine.

Refer to Filing systems for a list of filing system numbers.

E.g. set FSNR to 3 and FSRM to 4 to auto-load ADFS 1.30 into ROM slot 4.

Note that, if you auto-load a non-standard filing system, 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).

BOOT

This variable selects a boot activity, which is performed on every power up or BREAK.

(1) This is similar to using '*OPT 4 2' on disc filing systems.

(2) This may be useful, for example, if you want to run an alternative 'menu' program. E.g. put it as 'MyMenu' on a disc named '!Boot', put 'CHAIN "MyMenu"' in the disc's !Boot file, issue '*OPT 4 3', and go : CTRL-BREAK (the '!Boot' disc is now selected), SHIFT-BREAK ('MyMenu' now runs), and, when you've selected a disc, CTRL-SHIFT-BREAK (the selected disc now boots).

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

Press SHIFT during power up or BREAK to suppress the boot activity (e.g. in case your !Boot malfunctions).

SLOW

This variable selects the length of the artificial delay in returning 'tape bytes' to the Tape filing system (refer to Tapes for details).

0 is the minimum delay, 255 is the maximum delay. You may want to use a non-zero value if the tape loading speed is to appear more 'realistic'.

Values that approximate the speed of the standard 1200 baud tape system are around 128 (this includes the roughly 1 second gap between blocks) or 94 (excluding the gap). Note that gaps are not emulated. There is only a delay per byte. I.e. 94 is more accurate in terms of the signalling rate, while 128 results in a more accurate block rate.

WPRO

This variable configures flash card write-protection.

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

TUBE

This variable selects the speed of bulk transfers across the Tube (i.e. when data is transferred between a file and your second processor's memory). 2-byte transfers are almost twice as fast (75 KB/sec) as 1-byte transfers (40 KB/sec), and should (theoretically) be supported by all second processors.

(1) This is an experimental (and possibly unreliable) setting that reaches dizzying transfer speeds of well over 200 KB/sec. It seems to work OK on ARM7TDMI coprocessors, ReCo6502 second processors at 14 MHz, and all my 'soft' second processors at their highest clock speed. But do not trust this setting while working with valuable data.

COPR

You should generally leave this at 0.

It allows you to specify which type of co-processor you are using.

Normally, GoSDC doesn't need to know. However, if it's a 32016 Second Processor, it does need to know. The 32016 Second Processor cannot handle the maximum transfer speeds that Acorn documented for the Tube. GoSDC operates at those maximum speeds, so it needs to be 'throttled down'. I.e., if you're using GoSDC and a 32016 Second Processor at the same time, you must set COPR to 5. You may want to set TUBE to 2 as well.

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.

EIRD

You should generally leave this at 0.

It is only available on the Electron, and only effective when the new type Elk2GoSDC is used.

It contains eight 'disable bits', which, when set, disable the corresponding RAM banks on the interface, so the sideways ROM slots they use won't interfere with those used by other hardware expansions (e.g. ROM/RAM boxes). Only bit pairs can be set. To set bit 0+1, 2+3, 4+5, or 6+7 in the value, add 3, 12, 48, or 192 to it, respectively. This disables the RAM banks mapped to sideways ROM slots 0+1, 2+3, 6+7, or 12+13 respectively.

Error messages

The GoSDC ROM issues the following errors :

• 'Switch off Tube' (code 147)

  *SDCTool will not run code on your second processor, so please switch it off.

• 'Drive not available' (code 183)

  No currently selected disc contains the drive being accessed.

• 'Access outside drive' (code 183)

  An attempt was made to access data 'outside' the current drive space.

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

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

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

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

• 'Sensitive ROM slot' (code 201)

  *SDCSLoad / *SDCSSave will not write / read GoSDC's 'main' slot.

• 'Cannot open file' (code 214)

  *SDCSLoad / *SDCSSave was unable to open the source / target file.

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

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

• 'Unknown variable' (code 220)

  The name specified to *SDCConfig is not recognized.

• 'Prefix too long' (code 220)

  The name specified to *SDCPrefix is longer than 31 characters.

• 'Unknown ROM slot' (code 254)

  The specified ROM slot number is not in range (0 - 15).

• 'Escape' (code 17)

  Escape was pressed during *SDCList.

• 'ROM corrupted' (code 0)

  Your *-command will not be executed, because the GoSDC ROM has been corrupted. See also 'GoSDC : ROM corrupted !'.

• '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 : ROM corrupted !'

  The GoSDC ROM software checks itself for corruption on every power up (real or generated). The alert indicates that corruption was found. Power cycle your machine, and if the alert remains, proceed to How to recover. Thanks to Greg Cook for providing an especially fast implementation of the CRC algorithm.

• 'GoSDC : Cannot find auto-load FS'

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

• 'GoSDC : Bad slot for auto-load FS'

  You are trying to auto-load a filing system into an unsuitable ROM slot (i.e. occupied by the GoSDC ROM, or > 15).

• 'GoSDC : Press CTRL-BREAK now ...'

  You are running BBC Master MOS 3.50, and have auto-loaded a filing system into ROM slot 4, 5, 6 or 7. If the usual power up reset would be generated now, it would cause the slot to be wiped again by the MOS. Since CTRL-BREAK is the next best thing, but can't be generated, you are asked to do it yourself.

• '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 'write only' mode, so the corrupted flash ROM contents can no longer hang the machine, but can still be overwritten. SDCUP is the tool to use (refer to its discussion for details).

Follow the following recipe :

1) Power down.

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

3) Power up. Your machine should no longer hang, but GoSDC has 'gone' as well.

4) Run SDCUP *.

5) Power down.

6) Move the 'enable/disable' jumper on GoSDC's configuration header back to pins 4+6.

7) Power up. Your machine should no longer hang, and GoSDC is back in action.

* Note that, since GoSDC is temporarily unavailable, you need a way to transfer SDCUP to your machine. If there is no way, you may want to consider making a Tool ROM (burn TOOLROM into a 16 KB PROM and plug that into a free sideways ROM slot) and run SDCUP from there (enter  *ROM ,  *OPT 1 2  and  *Cat  to list, and enter e.g.  CHAIN "SDCUP"  to run). You will find the relevant files in the appropriate subdirectory of this directory.

What is remembered

Choices made through *SDCConfig, *SDCSPlug, *SDCPrefix, *SDCDisc and *SDCTape 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.