Proposal: Format/Verify disc invocation

[gerph]

(from Skype discussion)

As the Filer won't be providing the ability to format discs, I would recommend a mechanism for launching the Format tool independant of the main filer icon.

Problem statement

The formatting tools differ between those that can be used by the Floppy disc filing systems, and the HardDisc filing systems. They also differ between the different hardware drivers. The format tool for floppies has traditionally been built into the Filer. The format tool for hard discs has traditionally been the command line tool HForm which required much work. Presumably other formatting tools now exist, which can provide some better mechanisms for formatting discs.

Additionally, there will be a need in the future to create a better disc layout system, for partitions and the like. Partitions are not considered here - only the layout of the filing system within a disc.

Terminology

• Driver: A FileCore hardware driver, such as ADFS, SCSIFS or RAMFS. May support multiple Devices, currently up to 8 with the extant interface for FileCore discs.
• Device: A physical or virtual device which may be used to access a Filing system through a Driver. Devices may be removeable, such as USB devices.
• Disc: A set of logical blocks on a media provided by a Device. Discs may be removeable, such as 3 1/2" discs, SD cards or USB drives, or they may be attached, such as SATA hard discs.
• Filing system: A layout on a Disc which provides access to files, using the logical block access probided by the Device.
• Floppy disc: Within this document, a 'Floppy disc' is a disc which uses the FileCore mount and layout mechanism used by traditional floppy discs. As the FileCore layout for a Floppy disc differs from that for a Fixed disc, this differentiation is necessar.
• Hard disc: Within this document, a 'Hard disc' is a disc which uses the FileCore mount and layout mechanism used by traditional hard discs. This differs from the Floppy disc layout in having a boot block and disc record.
• Removeable: A disc which can be removed from the system at runtime. Options may be available to Eject the disc, as indicated by the FileCore flags.
• Fixed: A disc which cannot be removed from the system.
• Formatting: Erasing and laying out a Filing system on the Disc.
• Checking: Performing an integrity check of the Filing system on the Disc.
• Verifying: Performing a check of the reliability of the Disc media. Does not involve the filing system.

Requirements

There are 3 major operations that are required for filing systems on discs:

• Formatting - traditionally in ADFSFiler, *Format, or HForm.
• Verifying - traditionally in ADFSFiler, or *Verify.
• Checking - traditionally *CheckMap or using DiskKnight.

It should be possible to offer different filing system formats. These formats are provided by the Service_EnumerateFormats call. It should be possible for Filers to offer those submenu items to format the disc in those formats for floppy discs, or to allow the formatter to handle these itself. It should also be possible to provide alternative formats if they need to. The use of the Service_EnumerateFormats call is not defined, here but any mechanism should be compatible with it.

The formats which must be supported by the system include for Floppy discs and Hard discs. Floppy disc formats provided by the RISC OS FileCore system are L, D, E, F, E+, F+. ImageFS extensions provided by DOS FS and others allow formatting of DOS style discs. Hard disc formats may be dependant on the filing system.

Distinct tools may be required for these operations, and so should be able to be invoked for each
combination of operations.

The interface proposed must follow the existing mechanism used by RISC OS applications.

The interface proposed must be able to be used outside of the Desktop, to allow it to be used as a recovery mechanism.

Proposal

The interface proposed here is a collection of *-command to invoke a tool, which are discovered using system variables. An additional interface is provided within the desktop to allow the selection of a format within a running disc formatting application.

Variables

The commands provided are in the form of the Alias$@ types. A few variations are available in the *-Command:

• <operation> - the operation being performed as a string: Format, Verify, or Check.
• <type> - the disc type, as a string: Floppy, Hard
• <driver> - the driver name, eg ADFS.
• <cli> - the string CLI for command line only invocation, or empty for desktop.
• <device> - identifier number for the device to be acted upon, eg 0, 4. Names should not be used.

The system variables which should be used for the operations are:

• Alias$@FS<operation><cli>_<type>_<driver> - defines command should be used to invoke the operation on a specific driver, or the string error to prevent the use of this tool.
• Alias$@FS<operation><cli>_<type> - defines command should be used to invoke the operation on generic devices, or the string error to prevent the use of this tool.

The string error is used so that blind invocation of the command will fail.

Checking availability

A tool wishing to check whether a given disc can be formatted should perform the following sequence of operations:

• Check the above variables in order, substituting the values for the operation requested.
  • If the variable does not exist, move on to the next variable.
  • If the variable is set to error, stop - the operation is not possible.
  • If the variable is set, stop - the operation is possible and the value is the command prefix that should be used.
• If no variables are set, stop - the operation is not possible.

For example, the ADFSFiler for device 4 would decide whether the formatter was available by checking the variables:

• Alias$@FSFormat_Hard_ADFS
• Alias$@FSFormat_Hard

Invoking operations

A tool wishing to perform an operation would perform the above steps and then:

• If a value had not been found, report an error to the user. This would only happen if the variable was available when the options were created in menu or dialogues, but deleted by the time of invocation.
• When running in the desktop (to allow an already running application to handle the operation):
  • Broadcast a Wimp message &XXXX0 (Message_FSOperationRequest), recorded delivery:
    • +20 Operation number, as a byte:
      • 0: Format
      • 1: Verify
      • 2: Check
    • +21 Disc type, as a byte:
      • 0: Floppy
      • 1: Hard
    • +22 Device number, as a byte:
      • 0-7: device number
    • +23 Reserved for future expansion, must be 0.
      Handlers should ignore this message if this byte is not 0.
    • +24 Driver name, as a 0-terminated string in 16 bytes
    • +40 (for Format) Filing system format name, as a 0-terminated string in 32 bytes, or an empty string for general format handled by the application.
      (for other) Reserved, must be an empty 0-terminated string.
  • Handlers will acknowledge this message if they can handle the request.
  • If the message bounced, the sender should continue to invoking the command requested.
• If a value had been found, append parameters to the command line in the form:
  • -op <operation> -type <type> -driver <driver> -device <device>
  • An optional -format <fs-format-name> may be supplied to request a specific format.
• When running in the desktop, issue Wimp_StartTask with the constructed command.
  • Wimp messages will be sent (as described below) when the operation is being performed.
• When running outside the desktop, issue an OS_CLI with the constructed command.
  • The return code from the application will indicate the status of the operation:
    • 0: Operation completed successfully.
    • 1: Operation was aborted by user without changes made.
    • 2: Operation completed but with errors that were addressed.
    • 3: Operation was aborted by user after changes had been made.
    • 4: Operation failed (or completed but errors could not be addressed).
  • A RISC OS error is equivalent to return code 4.

Desktop operation

The handler for the disc operation (the FS Operation Application, 'FSOA') must support a few Wimp messages as part of this protocol.

• Message &XXXX0 (Message_FSOperationRequest).
  • Broadcast by an application requesting an operation to be performed on a disc, as described
    above.
• Message &XXXX1 (Message_FSOperationStatus).
  • Broadcast by an FSOA when a given disc has changed in state:
    • +20 Operation number, as a byte:
      • 0: Format
      • 1: Verify
      • 2: Check
    • +21 Disc type, as a byte:
      • 0: Floppy
      • 1: Hard
    • +22 Device number, as a byte:
      • 0-7: device number
    • +23 Reserved for future expansion, must be 0
      Handlers should ignore this message if this byte is not 0.
    • +24 Driver name, as a 0-terminated string in 16 bytes
    • +40 Status code, as a word:
      • 0-255: Operation has completed, status codes as for the CLI return code above.
      • 256: Operation has started
      • 257-511: Operation progress notification (may optionally be sent as the operation progresses).
  • This message must not be acknowledged.
  • Clients may disable their functions once a 'started' notification is received, and enable them once the completion notification is received.
  • Clients may provide a progress indicator, but it should be assumed that the FSOA has an interface to show the status itself.

[gerph]

Part of this is now implemented - the part that does the command invocation.

The part that does the Wimp message isn't.

[gerph]

And it needs some proper documentation writing too.

[c-jo]

Looking at this again, it seems this is more general than just filers? Perhaps it should be a separate thing, which is usey by FilerX?

[gerph]

That's why it's protocol to launch the tools - all that's being defined here is how you launch them. The Formatter/verifier/checker backup/etc tools are entirely separate. And could be used by other things too.
We could easily strip out the ability to launch such tools from the menus, but the point was to retain the /ability/ to have feature parity, without actually providing the ugly formatting and verify tools that we don't want to do in FilerX.