DiscMedic 0.11
==============

DiscMedic checks and repairs hard discs, SD cards, NVMe drives and USB
drives, in the formats a RISC OS machine meets: FileCore, which is what
RISC OS formats its own discs as, FAT, which is what almost everything else
uses, and - on RISC OS 64 - UFS2 and btrfs.  It also looks after the
configuration memory (CMOS), and can keep a copy of it in the boot
partition.

Copyright (c) 2026 Martin Eastwood.  MIT licence; see the Licence file.


Before you start
----------------

1.  Check before you repair.  A check writes nothing at all, and the report
    tells you what a repair would do.

2.  Copy off anything you cannot lose.  A disc that needs repairing is a
    disc that has already surprised you once.

3.  Have somewhere for the undo file that is not the disc being repaired.
    Another drive, or a RAM disc, is fine.  DiscMedic refuses to put the
    undo file on the disc it is about to write to, because an undo file
    that dies with the disc is worse than none at all.

    It normally goes in the scrap directory, which is on the machine's own
    disc.  When that is the disc being repaired, DiscMedic moves it to the
    RAM disc for you as soon as you choose the disc, and says so.  Remember
    that a RAM disc does not survive a reset, so undo what you are going to
    undo before restarting.  If there is no RAM disc, make one with
    Configure, Discs, RAM disc size, or name a directory on another drive.

4.  Close anything that has files open on the disc, and dismount it from
    its icon bar menu.  A filing system that is still caching the old
    layout will write it back over the repair.

5.  Reset the machine after a repair, before using the disc again.


The window
----------

Click SELECT on the icon bar icon, or choose DiscMedic... from its menu.
The window has two halves: what you ask for on the left, the report on the
right.

  Discs           every disc DiscMedic can see, and what it found on it.
                  Click one to choose it.  Rescan looks again, after you
                  plug something in or change a card.

  Scan Type       Quick check looks at the parts that decide whether the
                  disc will mount at all.  Full check reads every file and
                  directory as well.  The detailed full check explains how
                  it reached each conclusion.

  Repair what is found
                  without this DiscMedic only looks.  With it, it puts
                  right what can be put right.

  Make an undo file
                  saves the old contents of everything that changes.  The
                  field beside it says where; it must not be on the disc
                  being repaired.

  Recover lost data
                  lost pieces of file are normally returned to the free
                  space.  Select this to keep them in Lost+Found.

  The bar         shows how far through the disc the work has got.  (A
                  machine without Toolbox32 shows a slider instead; it
                  does the same.)

Click Check (or Repair, once you have asked for a repair) and the report
appears as it is produced.  Stop ends a run between sectors.  Save report
writes the report as a text file: it is what you would send to somebody
helping you with the disc.


The boot partition and the CMOS
-------------------------------

A Raspberry Pi, and other machines that start from an SD card or a drive,
keep a small FAT partition beside the RISC OS one.  The firmware reads it
before RISC OS is running, and on a machine with no battery-backed CMOS of
its own the file called CMOS in its root directory is where the
configuration memory is kept between sessions.  DiscMedic reads and writes
that partition with its own FAT code, so it works whether or not the
machine has mounted the partition.  The partition is the first FAT volume
on the disc you chose.

  Look inside...  lists the root directory of the boot partition and says
                  whether it has a CMOS file and whether that file is
                  sound.  Nothing is written.

  Back up CMOS    saves the configuration memory as the file CMOS in the
                  root of the boot partition.  A file that is already
                  there is overwritten in place; otherwise it is made.
                  Nothing else on the partition is touched.  It is saved
                  with *SaveCMOS, so it is exactly what SDCMOS and the
                  loader expect.  It is refused if the configuration's own
                  checksum is wrong, since that would be a bad backup, and
                  read back afterwards to make sure it is the same.  Like
                  a repair, it writes to a disc, so it makes an undo file
                  first.

  Restore CMOS    puts the saved configuration back with *LoadCMOS.  The
                  file is checked first, and refused if it is damaged.
                  Restart afterwards for every setting to take effect.

The icon bar menu's CMOS submenu offers the same two, along with showing
and mending the checksum and resetting the settings.

From the command line:

  *DiscMedic -boot info   SDFS 0
  *DiscMedic -boot list   SDFS 0
  *DiscMedic -u RAM::RamDisc0.$.Undo -boot backup SDFS 0
  *DiscMedic -boot restore SDFS 0
  *DiscMedic -boot backup -bootname CMOS.OLD -noundo SDFS 0

-part <n> names the partition if it is not the first FAT volume.


Using the engine from the command line
--------------------------------------

The front end never touches a disc.  It works out what you want and runs
the engine, DMEngine, in a task window.  You can run the engine yourself,
which is what to do when the Toolbox modules are on the disc that will not
mount:

  *DiscMedic SCSI 4                 check drive 4 on SCSI
  *DiscMedic -f -u RAM::RamDisc0.$.Undo SCSI 4    repair it, with an undo file
  *DiscMedic -r RAM::RamDisc0.$.Undo SCSI 4       put it back again
  *DiscMedic -image $.disc/img             check a disc image

Run *DiscMedic -h for the full list of options.


What the report means
---------------------

Every line is marked with what kind of line it is:

  (nothing)   information
  *           something is wrong
  -           something has been put right
  +           something has been created
  >           something has been written to the disc
  !           the disc would not read or write

The last few lines say how many faults were found, how many were repaired,
and what to do next.


What DiscMedic checks
---------------------

On a FAT12, FAT16 or FAT32 volume, everything: the boot sector and, on
FAT32, the backup copy of it and the FSInfo sector; every entry in the file
allocation table; the second and any further copies of the table against
the first; every directory, long file name and short file name; every
file's cluster chain against its recorded length; clusters claimed by two
files at once; circular chains; clusters that belong to nothing; and the
flags that say whether the volume was shut down cleanly.

On a FileCore volume: the defect lists and their check bytes; the boot
block checksum; every field of the disc record; where the map is; the check
byte of every zone of both copies of the map; the cross check that ties a
copy together; the free space chain of every zone; the map's copy of the
disc record against the boot block's; and then the whole directory tree.

See Docs.Limits for the honest list of what has been tested and what has
not.


Undoing a repair
----------------

The undo file holds the old contents of every sector the repair changed,
so putting it back restores the volume exactly.  It is written in absolute
sectors of the whole drive and carries a fingerprint of the drive it came
from, so it cannot be applied to the wrong one by accident.

  *DiscMedic -r <undo file> <filing system> <drive>

DiscMedic refuses to restore an undo file that does not match the drive.
If you are certain it is the right one - because you have since reformatted
the drive, say - add -force.
