ADFFS v2.73o 02/06/20 written by Jon Abbott
-------------------------------------------

ADFFS provides emulation of the 1772 / 710/711 floppy disc controllers,
and emulates ADFS responses to disc requests.  ADF, APD and JFD floppy
disc images can be mounted to floppy drive 0 as if they were physically
inserted.

To associate floppy image files with ADFFS, ensure their file type is set
to Floppy (&FCE).  You may then mount the floppy by double clicking the
image file.

Please ensure your system is configured for at least one floppy drive, this
is then redirected to ADFFS when a disc image is mounted.  For OS builds that
do not include ADFS (eg Pi), a stub Module is automatically loaded which
emulates ADFS.

ADFFS supports the following floppy image formats:

F - 1600K, 77 entry directories, new map
E - 800K, 77 entry directories, new map
D - 800K, 77 entry directories, old map
L - 640K, 47 entry directories, old map
Atari 360K
Atari 720K
DOS 720K
DOS 1.44M

ADFFS also has the ability to provide a virtual machine based on the
IOC/MEMC/VIDC1 chipset, running RISC OS 2.0 through to RISC OS 3.71.  When
games are run via the "Boot floppy" menu option, this is automatically
started if the game won't run on the machine you're attempting to run it on.

Whilst the VM is enabled, the current task runs as if it's running on
an ARM3 processor.  Instructions that aren't supported or behave differently
on the physical CPU are translated to code that will work.

The VM also supports software based on APCS-A and APCS-R, suitable CLib
Modules are loaded automatically into the VM environment when code attempts
to invoke CLib.

ARM3 emulation is handled via a JIT, which examines the code once when
it's first seen and only modifies incompatible or ambiguous instructions.
The code then executes natively on the physical CPU, with the JIT only being
invoked when either new instructions are seen or self-modifying code has
modified existing instructions.

As the code runs natively on the CPU, it executes at a speed roughly
equivelant to an ARM3 clocked at around 91% of the CPU MHz in the case of a
Pi3.  This enables games that wouldn't ordinarily run on an ARM6 or 7 because
of incompatibilities to still run faster than they would on an original ARM3.
Likewise a StrongARM can run ARM6/7 code faster than the original CPU's.

ADFFS accounts for CPU speed differences, games are regulated at their
original intended speed and any known bugs are corrected where possible.

ADFFS has a VIDC20 and VIDC1 emulator built in.  When games are run on
a machine that has a GPU, the screen is translated to a 16M colour
equivelent.  For this to work, legacy MODE resolutions must by supported
by your monitor, either via an MDF file or in the case Pi's, the hardware
upscaler must be enabled by disabling EDID.

When games are run on a RiscPC that were originally written for the original
Archimedes series, VIDC1 commands are translated to VIDC20 commands on-the-fly
and screen writes are redirected to the RiscPC screen buffer.

When used in conjunction with USBJoystick (see JASPP forum Pi\Development
to download) on machines with USB ports, Acorn, RTFM and Serial Port/Vertical
Twist Joystick interfaces are emulated and for games that don't natively
support Joystick, keys can be mapped to Joystick movement and the fire button
via *ADFJoystickKeys.




Commands
--------
*ADFMount <file>  load an ADF/APD/JFD into memory

*ADFOpen <file>   load an ADF/APD/JFD into memory and open a filer window

*ADFSave <file>   save a mounted ADF to disc

*ADFEject         remove the mounted image from memory, losing changes

*ADFFlush         write changes back to original ADF file

*ADFRecord <file> start recording DiscOp's and save to file
                  when Ctrl-Shift-F10 is pressed

*ADFStop          stops recording DiscOp's, equivalent to Ctrl-Shift-F10

*ADFDoNothing [x] does nothing, use with Set Alias$<Command> to prevent
                  destructive commands

*ADFBootFloppy    simulates a Shift-Break soft-reset to boot a floppy

*ADFProtectModules [ON | OFF]   prevents essential modules from being removed.
                                No parameter implies ON

*ADFProtectCMOS [ON | OFF]      prevents the CMOS from being changed
                                No parameter implies ON

*ADFHideHourglass [ON | OFF]    doesn't display an hourglass when loading
                                floppy images
                                No parameter implies ON

*ADFForceVSync <n / 0>   ensures a delay of <n> centiseconds between screen
                         buffer swaps, and forces a VSync if one hasn't
                         happened since the last frame swap.
                         eg. ADFForceVSync 4 would force a game to run at
                             25 FPS

                         NOTE:  Can be used to slow down games

*ADFWriteProtect [ON | OFF]         prevents writes to the floppy image
                                    No parameter implies ON

*ADFEmulateFDC [n]                  Emulate a specific Floppy Controller:
                                    710, 711, 1772.  If no FDC is specified it
                                    will reset to the controller in the machine,
                                    or 710/711 if none present

*ADFReserveMemory <n | 0>           Reserve nKB for ADFFS
                                    
*ADFPause <n>                       pause for <n>ms
                                    
*ADFVoices <n>                      sets the number of sound channels

*ADFScreenCaching <ON | OFF>        turns off screen caching on RISC OS 4
                                    when a StrongARM is present

*ADFRemapVideoMemory [<mode> <size>] remaps video memory to match RISC OS
                                     3.1 and switches emulation to RISC OS 3.11

*ADFEmulateRISCOS [OS version]      switches SWI behaviour and sound settings
                                    to the RISC OS version specified.
                                    eg. 3.11 will default sound values to
                                    length=208 and Period=48
                                    No parameter turns off emulation




RISC OS 5 commands
------------------
*ADFJoystickKeys <J1 Right> <J1 Left> <J1 Down> <J1 Up> <J1 Fire> [<J2 Right> <J2 Left> <J2 Down> <J2 Up> <J2 Fire>]
                                    translates Joystick movement into key
                                    presses.  Refer to PRM1-158 or the URL
                                    below for key numbers.

Key numbers: "https://www.riscosopen.org/wiki/documentation/show/Low-Level Internal Key Numbers"




JIT commands (RISC OS 3.5+)
---------------------------
*GOARM3JIT <address>     equivelant to *GO, but runs the code as if its
                         running on an ARM3 (ARMv3).  An address of 0 turns the
                         JIT on, but doesn't execute any code.  With no
                         address it shuts the JIT down.

*GOARM4JIT <address>     equivelant to *GO, but runs the code as if its
                         running on a StrongARM (ARMv4).  An address of 0 turns
                         the JIT on, but doesn't execute any code.  With no
                         address it shuts the JIT down.

*JITMEMORYA [P] <address> <current value> <new value> [<Module title>]
                         replace an instruction at <address> if matched with
                         <current value>.  Use P to make the change persistent,
                         if it needs to be replaced more than once.
                         If a Module instruction needs replacing, <address>
                         is the offset from the start of the Module file and
                         the exact Module title should be specified at the
                         end of the command.

*ADFCACHE [ON | OFF]     emulates turning the CPU cache on/off when the JIT is
                         running in ARMv4 mode

*ADFGO <address> [;environment]
                         performs a *GO to JIT application space if the JIT
                         is running

The following commands mirror the MemAlloc module:

*ScreenSize / *SystemSize / *RMASize / *SpriteSize / *FontSize
*RAMFSSize / *RMAFree / *SpriteFree / *FontFree / *RAMFSFree



Keys
----
CTRL-SHIFT-F1 thru F9            Change to disc 1..9
CTRL-SHIFT-PAGE UP               Slow game down (add 1cs delay at VSync wait)
CTRL-SHIFT-PAGE DOWN             Speed game up (remove 1cs delay at VSync wait)
CTRL-SHIFT-LEFT ARROW            Mono audio to left channel
CTRL-SHIFT-RIGHT ARROW           Mono audio to right channel
CTRL-SHIFT-DOWN ARROW            Stereo audio
CTRL-SHIFT-F10                   Save floppy image recording file
CTRL-SHIFT-F12                   Quit to desktop (StrongArm and above)
                                 NOTE: This only works for games running
                                       under the JIT



General use Environment variables
---------------------------------
ADFFS$ARMv7             0 - CPU is not ARMv7
                        1 - CPU is ARMv7
ADFFS$Dir                   ADFFS home directory
ADFFS$CPUID                 CPU ID, values are:
                        2 - ARM2 / 250
                        3 - ARM3
                     &610 - ARM610
                     &620 - ARM620
                     &700 - ARM700
                     &710 - ARM710 / 7500
                     &A10 - StrongARM
                    &xxxx - Later processors will have a 4 digit value
ADFFS$HighVectors       0 - Low Vectors
                        1 - High Vectors
ADFFS$OSVersion             OS version in BCD format.  eg &37100 for 3.71
                            RISC OS 6 will be reported as RISC OS 4.x to
                            allow for 32bit OS detection to use >=&50000
ADFFS$VIDC20            0 - No VIDC20 present
                       >0 - VIDC20 address



!Boot environment variables
---------------------------
ADFFS$FileSizeLimit  max size of file ADFFS will load in KB (2048 max on RO3.1)
ADFFS$LCDGM          Y / N - enable LCDGameModes by default (RO 3.1 only)
ADFFS$RecordingPath  default path to save recordings created via ADFRecord



Boot scripts
------------
Boot scripts are run when "Boot floppy" is used from the Filer menu and a
JFD floppy image is mounted.  Scripts should be placed in !ADFFS.obey and
named to match the floppy ID and disc number in the set. eg F1000101 for
2067BC (F10001 - the id and the last two digits denote disk 1)

ADFFS comes with boot scripts for many games that have been tested and/or
officially released, these generally either fix issues with the original
game loaders or add compatibility for later processors and RISCOS versions.



!Boot overrides
---------------
Some games do things they shouldn't in their !Boot, such as auto-launch or
load Modules.  These can be overidden by creating an alternative !Boot under
!ADFFS.override.  The !Boot file should mirror the original, loading icons
and setting up environment variables etc and be placed in an identical
application directory as the original game, under a folder that matches the
floppy ID.  eg for Gribbly's Day Out:

!ADFFS.override.F1017901.!Gribbly.!Boot



Multi-disc support
------------------
ADFFS supports multi-disc software, you can change the disc via hotkeys:
CTRL-SHIFT-F1 thru F9

For this to work, the last character of the filename must be the disc
number.  ie "FFT Disc 1" / "FFT Disc 2" etc



MIME / Transfer of files from PC's / FTPc
-----------------------------------------
When transferring files from a PC via FTPc, it can be useful to add MIME
types for floppy images so the file types are set correctly.  To do this
edit the MimeMap file, which can be found at:
!Boot.Resources.!Internet.files.MimeMap

Add the following MIME definition near the end of the file:

application/adffs	Floppy	FCE	.jfd	.adf	.apd



Known issues / features
-----------------------
1. Updates to mounted ADF's are not automatically flushed
   back to the original ADF file.  Use *ADFFlush or Flush
   from the Filer

2. The ADF file size limit can be changed in !Boot, the default
   and maximum of an ADF is 2048kb

3. RMTidy and RMClear are ignored whilst ADFFS is loaded

4. Uses memory between D00000 to 1000000 on RISC OS 3.1 to
   create a Dynamic area for loading floppy images

5. ADFFS will not work on a RO3.1 machine with more than 12mb of RAM



Imaging floppy discs as ADF (Amiga Disc Format)
---------------------------

ADF can be used to image unprotected floppy discs and is natively supported by
most Archimedes/RiscPC emulators.

1. Insert the floppy
2. Select "Image floppy\Image as ADF" from the ADFFS Filer
3. Select "Save as" from the ADFFS Filer to save the ADF file



Imaging floppy discs as JFD (JASPP Floppy Disc)
---------------------------

Requirements: 1900MB of free memory
              !SparkFS loaded if you want to attempt imaging using the
              recording files bundled with ADFFS

Imaging as JFD has several advantages over ADF, including capturing disc
protection sectors and allowing metadata to be stored within the image.

To image to JFD, you must have create a recording of the disc first, this
contains details of the disc geometry used to read the floppy and all sectors
that have been accessed.  ADFFS contains many recording files of titles JASPP
have already imaged, so you may not have to create your own recording files.
Skip to step 7 below, if you wish to see if ADFFS has a recording file for the
title you're attempting to imaging.


Creating your own recording files
---------------------------------
1. Clean boot the machine (this is to ensure the floppy has not been
   seen by ADFS)
2. Load !ADFFS
3. *ADFRecord adfs::4.$.Fiiiiidd
   Where:
     iiiii - is the ID (select the title in "Image as JFD" to find the ID)
        dd - is the disc number (eg 01, 02, 03 etc)

   eg Flashback disc 1 would be F1015901

4. Insert the floppy and copy all files to a temporary folder on your
   harddisc.  You may delete them as soon as the copy has finished,
   this step ensures all used sectors are seen by ADFFS
5. If you're imaging disc 1, run the game, once its fully loaded or prompts
   for another disc, press SHIFT-CTRL-F10.  If there's no protection or
   you're imaging disc 2 onwards, just press SHIFT-CTRL-F10 and skip to step 7
6. Reboot machine (if you've had to run the game)


Creating a JFD file
-------------------
7. Select "Image floppy\Image as JFD" from the ADFFS Filer
8. Select the title from the drop down, alter any fields as appropriate
   such as the floppy number and filename
9. The recording file will be selected automatically if ADFFS has an
   in-built recording of the title/disc in question. If no recording exists
   the imager will default to either "e-format800" or "e-format1600" for the
   recording file.
   If you wish to use your own recording, drag/drop the recording file into
   the imaging window
10. Drag/drop the "Save JFD as" icon to the folder where the JFD file should
    be saved
11. Ensure the floppy is in the drive and Click OK to start imaging
12. Send all of the JFD files and recordings to: jon@jaspp.org.uk
    or request FTP submission details



Converting APD images to JFD
----------------------------

1. Open the APD image with ADFFS
2. Select "Save as" from the ADFFS Filer to save as a JFD file



Converting Kryoflux recordings
------------------------------

Requirements: A Mac or PC with Java 7

1. Download the converter from:
    https://github.com/drdpj/kryotools/

2. Convert to an APD file using the following command:
    java -jar kryo2apd.jar [options] [kryodumpdir]



Scanning material
-----------------
All manual scans must be 600dpi, box/floppy scans should be
300dpi, required scans are as follows:

1. Both sides of the floppy discs (300 dpi)
2. Manuals, instructions etc.  Ensure all pages are scanned, including
   blank ones (or indicate blank ones), this is to ensure the PDF
   created by JASPP matches the original exactly (600 dpi)
3. Any addition material, such as stickers, posters books, pins.
   Photograph if it's not possible to scan them (300 dpi)
4. For boxes with inserts in plastic sleeves
     4.1 Take the insert out and scan (300 dpi)

   For printed boxes:
     4.2. Scan all sides of the top half (top, bottom, left, right, face)
          If any are identical, scan one and indicate, noting if it's
          flipped vertically.
     4.3. Scan all sides of the bottom of the box, indicating if any
          sides are the same and their rotation.

   For boxes with printing inside the box itself:
     4.4. Scan if possible, photograph if not.

NOTE: You can confirm your scanner is scanning at 300 DPI by checking
      a floppy disc scan is about 1050 x 1050 pixels once cropped
      


Contributions
-------------
Steve Harrison - LCDGameModes module, VIDC / Trackers and testing
Paul Vernon    - AutoVIDC module and testing
Jeffrey Lee    - ZLib module, oddbits code, 4-bit mode conversion code
Michael Drake  - !Sprites file
Darren Salter  - A5000
David Pitt     - Kinetic RiscPC 300
Kris Adcock    - Floppies: Elite, Chock Away, SimCity
                 Boxed games: Arcade Games Designer, Games Minipack 3
                 Manuals: Elite, Chock Away
Paul Oates     - Many adventure games from Magnetic Scrolls and TOPOLOGIKA
Fred Graute    - Assistance with fixing Throwback in extASM and additions
                 to StrongEd to aid in coding ADFFS
Xavier Louis Tardy - Iyonix, Eterna originals and various other games



Contact
-------
You can contact myself via the JASPP project: jon@jaspp.org.uk
Or via the JASPP forum: https://forums.jaspp.org.uk