LisaList2

Advanced search  

News:

2022.06.03 added links to LisaList1 and LisaFAQ to the General Category

Pages: [1]   Go Down

Author Topic: (Aphid Selector) Preview  (Read 3325 times)

stepleton

  • Sr. Member
  • ****
  • Karma: +109/-0
  • Offline Offline
  • Posts: 384
(Aphid Selector) Preview
« on: January 15, 2021, 07:40:07 pm »

On GitHub soon...
« Last Edit: January 19, 2021, 11:17:18 am by rayarachelian »
Logged

stepleton

  • Sr. Member
  • ****
  • Karma: +109/-0
  • Offline Offline
  • Posts: 384
Re: Preview
« Reply #1 on: January 15, 2021, 08:02:28 pm »

"Magic blocks" used by the Cameo/Aphid drive image selector

16 January 2021, stepleton@gmail.com

The Cameo/Aphid drive image selector program ("the Selector" for short) is a computer program for the Apple Lisa that allows you to create, manage, and boot from ProFile drive image files on a Cameo/Aphid ProFile hard drive emulator. Behind the scenes, the Selector accomplishes this by sending specially formatted read and write commands to (as yet unreleased versions of) the drive emulator that target unusual hard drive blocks.

The Selector is not the only program that can use these "magic blocks", and any hard drive emulator that understands these special reads and writes will be compatible with the Selector. This document describes the format of these reads and writes for the benefit of anyone who wishes to take advantage of this compatibility.

This document was created as part of the Cameo/Aphid hard drive emulator project at https://github.com/stepleton/cameo/tree/master/aphid.

Block FFFFFF: "Magic block" capability identification

The Selector reads from block FFFFFF to identify whether the connected drive is a ProFile emulator that supports the "magic block" protocol described here. If bytes $20-$2B of the returned block are Cameo/Aphid and bytes $2C-$2F are a 32-bit integer greater than or equal to $30303031 (i.e. 0001), then the Selector may assume that it is talking to a compatible emulator.

Note that ordinary ProFile hard drives respond to reads on block FFFFFF with "artificial" block data that contains information about the hard drive. Drives with ROM version $0398 that allocate no bad blocks or spare blocks only need bytes $00-$1F to encode this information, so the adjacent bytes occupied by the "magic block" capability identifier will not interfere with it.

Block FFFFFD: Built-in emulator commands

Writes to block FFFFFD with write count and sparing threshold parameters FE and AF respectively will issue "built-in" commands to the hard drive emulator. These commands are encoded in the block data written to the drive. ("Built-in" refers to an implementation detail of the Cameo/Aphid emulator and is not important to this description.) There are currently two commands:
  • If bytes $00-$03 of the block data are HALT, the emulator will immediately shut down after completing any uncommitted writes to the currently open hard drive image file.
  • If bytes $00-$06 of the block data are IMAGE:, then subsequent bytes should be a null-terminated string specifying the name of a hard drive image file. If this filename corresponds to an actual file, the emulator will flush any uncommitted writes to the hard drive image file currently in use, then then immediately close that file and open the specified hard drive image file in its place. The program issuing this command should give the emulator adequate time to switch between hard drive image files.
Neither command provides any response or any other overt indication of success or failure; programs should attempt to deduce the outcome in other ways.

(Note: the IDEfile emulator uses a similar but distinct "magic block" mechanism on block FFFFFD for access to its volume table.)

Block FFFEFF: Durable key/value store

Reads and writes to block FFFEFF provide access to a durable (i.e. retained through reboots of the hard drive emulator) key/value store. Keys are 20 bytes long; values are 512 bytes long. This store remains accessible no matter which disk image file is currently in use by the emulator.

The facility presents as having a kind of volatile (that is, not retained through system reboots) write-through cache where the 65,535 cache entries are software controllable (as opposed to being controlled automatically, as with a CPU cache for example). Cache keys are 16-bit values formed by the concatenation of the retry count and the sparing threshold specified during a ProFile read or a write. Reads can only request items from the cache, so earlier writes must have directed the store to have loaded data there from the durable key/value store. For writes, software must specify both a cache key and the 20-byte store key; the data will be saved in both the cache and the durable store automatically.

Operations:
  • ProFile reads to FFFEFF: Retrieve the cache entry assocated with the 16-bit concatenation of the retry count and sparing threshold parameters specified in the read. The store key will be the first 20 bytes of the returned data; the value is the remaining 512 bytes.
  • ProFile writes to FFFEFF with retry count and sparing threshold both set to $FF: Order the store to load key/value pairs into the cache. The data in the write has the following format:

          Byte      0: Number of key/value pairs to load (up to 24)

          Bytes   1-2: 2-byte key for the cache entry receiving the first value
          Bytes  3-22: 20-byte key of the value to load into that cache entry

          Bytes 23-24: 2-byte key for the cache entry receiving the second value
          Bytes 25-44: 20-byte key of the value to load into that cache entry

    And so on.
  • ProFile writes to FFFEFF with any other retry count and sparing threshold parameters: Write data to the cache entry specified by the parameters and to the key/value store. The store key is the first 20 bytes of the data, and the value is the remaining 512 bytes.
From a logical perspective, any store keys not yet associated with any data are paired with 512 $00 bytes, and any cache keys not yet associated with any data are associated with 532 $00 bytes (in other words, an all-$00 20-byte key and 512 bytes of all-$00 data).

Block FFFEFE: Filesystem operations

Reads and writes to this block enable some basic filesystem operations.  For safety, operations may be limited to files with a particular suffix.

Operations:
  • ProFile reads to FFFEFE: Retrieve information about a file in the current working directory. The emulator maintains a list of files (usually limited to those with a specific suffix, like ".image"), and a read obtains information about the n'th file in the list, where n is the 16-bit concatenation of the read's retry count and sparing threshold parameters. The contents of the 532-byte reply are:

          Bytes    0-3: Nonce
          Bytes    4-5: Number of files in the directory (suffix-limited)

          Bytes   6-19: YYYYMMDDHHMMSS ASCII last-modified time for the file
          Bytes  20-29: 10-character ASCII right-justified space-padded file size
          Bytes 30-275: Reserved, unused for now
          Bytes 276-??: Filename (length varies---up to 255 characters long)

             Remainder: $00 bytes, so the filename is null-terminated.
                        (There is always room for at least one null terminator.)

    By counting through values of n in the ProFile read parameters, programs that talk to the emulator can download a complete directory listing to present to the user. Programs that do this should save the nonce value at the beginning of one of the replies, which will change if and only if the contents of the current working directory change: as long as the nonce stays the same, the program will not need to download a new directory listing.

    (This strategy will not notice changes to file metadata like last-modified times or file sizes; the program will need to download a complete listing again if it's important to keep that data up-to-date.)

    If the program specifies an n greater than or equal to the number of (suffix-limited) files in the directory, the reply will list an empty 0-byte file with a length-0 filename.

  • ProFile writes to FFFEFE: Order the Cameo/Aphid to perform a filesystem operation in the current working directory, or change some aspect of the behaviour of the "magic block". Here, the 16-bit concatenation of the write's retry count and sparing threshold parameters direct which operation to perform, and the data contents are the parameters. Excess space in the parameter data may be padded arbitrarily.

    For readability, the 16-bit command is usually made of ASCII characters. Commands are:

    • 'cp': copy a file. Parameters are a null-terminated source filename and a null-terminated destination filename immediately following. There must be no existing file at the destination.
    • 'mv': move a file. Parameters are a null-terminated source filename and a null-terminated destination filename immediately following. There must be no existing file at the destination.
    • 'mk': create a new disk image. The only parameter is a null-terminated filename for the new image. There must be no existing file by that name.
    • 'rm': remove a file. The only parameter is the null-terminated name of the file to remove.
    • 'sx': set the file suffix to the one null-terminated parameter. The emulator will only list or operate on files that end with this suffix. (For file extensions like '.image', you must include the '.' character.) It is valid to specify an empty suffix.

    The emulator may refuse to carry out any of these operations for any reason. Furthermore, no feedback is returned about whethere an operation has been successful. For any operation that modifies the filesystem, one workaround is to perform a read and see whether the nonce has changed.
Filenames are sent to and from the emulator in the ISO-8859-1 (Latin-1) character encoding.

Block FFFEFD: Emulator status

Reads of this block retrieve basic system status information from the emulator. The format in use is a good fit for emulators that incorporate Unix-like operating systems (like Cameo/Aphid does) but may not be as useful for other implementations.

   Bytes   0-9: DDDDHHMMSS ASCII uptime; days right-justified space padded
   Bytes 10-24: ASCII right-aligned space-padded filesystem bytes free
   Bytes 25-31: ASCII null-terminated 1-minute load average
   Bytes 32-38: ASCII null-terminated 5-minute load average
   Bytes 39-45: ASCII null-terminated 15-minute load average
   Bytes 46-50: ASCII null-terminated number of processes running
   Bytes 51-55: ASCII null-terminated number of total processes
« Last Edit: January 15, 2021, 08:52:03 pm by stepleton »
Logged

rayarachelian

  • Administrator
  • Hero Member
  • *****
  • Karma: +101/-0
  • Offline Offline
  • Posts: 772
  • writing the code,writing the code,writing the code
    • LisaEm
Re: Preview
« Reply #2 on: January 15, 2021, 10:48:36 pm »

Congrats! Very nice!
Logged
You don't know what it's like, you don't have a clue, if you did you'd find yourselves doing the same thing, too, Writing the code, Writing the code

snuci

  • Full Member
  • ***
  • Karma: +9/-0
  • Offline Offline
  • Posts: 38
Re: Preview
« Reply #3 on: January 16, 2021, 09:22:33 pm »

Looks VERY interesting!  Please keep us updated on your progress.
Logged
Pages: [1]   Go Up