tsvm/serialdev.txt

All peripherals using serial connection must follow these standards

0. How to communicate

0.1 Master-to-Slave mode

- Master device must send enquiry query, and when slave device report READY, master must pull the answer from the slave

0.2 Master-to-Master mode

- One peer sends enquiry, and other peer writes the answer into the requester device. You know the transaction is done
  when other peer reports READY, NOT READY, and READY again.

1. ENQUIRY commands

1.0 All ENQUIRY commands have following syntax:

    <COMMAND-STRING> 0x17
    <COMMAND-STRING> 0x1E <ARGUMENTS-STRINGS SEPARATED BY 0x1F> 0x17
    In case of positive acknowledge:
        0x06 <ANSWER-STRINGS SEPARATED BY 0x1F> 0x17
    In case of negative acknowledge (e.g. error messages):
        0x15 <ANSWER-STRINGS SEPARATED BY 0x1F> 0x17

    All ENQUIRY commands are RECOMMENDED to be no larger than 4096 bytes
    STRINGs only consists with printable ASCII subset

1.1 WHO-ARE-YOU commands

    DEVTYP

Description: type of the device
Returns: type of the device, of which but not exhaustive:

- PRNT: Printer
- STOR: Storage device (floppy drive, etc.)
- COMM: Modem (slave-mode device)
- COMP: Modem (master-mode device, typically an other computer connected though a null-modem)

    DEVNAM

Description: enquires canonical device name
Returns: canonical device name in ASCII, maximum 4095 bytes

Note: non-standard device types must have LONGER THAN 4 characters of DEVTYP

1.2 CONTROL commands

    DEVRST

Description: resets the device
Returns: none

    DEVSTU

Description: reads status of the device, if applicable
Returns:
    <status code> <0x1F> <message string> 0x17
Status Code is single byte number, negative numbers (or >= 128) is used for negative response by convention.
Also see section 1.0

2. Device-specific commands

2.0 Command formats

    Device-specific commands does NOT have any header nor footer

2.1 STORage devices

2.1.0 NOTE

    - comma-followed-by-drive-number can be omitted; drive number 1 will be substituted
    - drive number always starts at 1

2.1.1 File Control

    OPENR"<path to file>",<drive number>

Description: opens the file for reading

    OPENW"<path to file>",<drive number>

Description: opens the file for writing

    OPENA"<path to file>",<drive number>

Description: opens the file for appending (a variant of write)

    WRITE<bytes to write>

Description: puts the device into WRITE mode and sets internal counter. Any subsequent messages will be interpreted
             as-is, get written directly to the file, and will decrement the internal counter accordingly.
             The number of bytes are required because of a nature of block-transfer, where every message is always in
             the length of the block size.

    FLUSH

Description: flushes any internal output buffer and no longer puts the device to WRITE mode

    READ

Description: reads one block of file. Any subsequent read attempts will return next block. If file size is lesser
             than a single block, rest of the bytes will be filled with zero, and size-of-the-block (see terranmon.txt)
             will be set accordingly.

    CLOSE

Description: closes any file that is open.

    LOAD"<path to file>",<drive number>

Description: loads a file onto the main memory. The pointer to the file will be sent back to the host device.

    LOADBOOT,<drive number>

Description: loads a bootloader so that it can be read by the host device through the serial connection.
             Technically there's no limit on the size of the bootloader but it's up to the BIOS to read more than
             a single block.

    CHTYPE,<file type>,<drive number>

Description: changes the open file's file type (or its extension)

    LIST

Description: lists contents of the open (with OPENR) directory in READABLE FORMAT
             (no 0x17 at the end, terminates string with zero)
             When a file is opened instead of a directory, its filename should be printed
             Raw filesystem (e.g. EPROM) should return first 4096 bytes of its contents.

    LISTFILES

Description: same as the LIST, but in machine readable format, which follows the following format:
             <file/dir type> <filename> [<0x1E for separator> <file/dir type> <filename> ...] <0x17>
             file/dir type: 0x11 for file, 0x12 for directory

    USAGE,<drive number>

Description: returns following values: TOTAL_SPACE 0x1E USED_SPACE 0x1D TOTAL_FILE_COUNT 0x1E TOTAL_DIRECTORY_COUNT in
             ASCII string.
             For non-hierarchical system, TOTAL_DIRECTORY_COUNT is always 0x30 (ASCII string "0")

    FSTYPE,<drive number>

Description: returns filesystem type in plain string, of which but not limited to:

    - TREE: any generic filesystem with recursive directories and multiple files.
            When emulators use filesystem of running OS for the disk implementation (and not use proprietary binary
            file), this type should be returned.
    - FLAT: filesystem without directories and can hold multiple files. E.g. Commodore 64
    - RAW: no filesystem is used. E.g. EPROM

    When disk image is used for emulation, their identifier should be returned. E.g. FAT, TEVD

2.1.2 File type dictionary

    - PRG: executable
    - TXT: text document
    - BIN: binary data
    - SEC: pseudo-type used by an pseudo-file called "!BOOTSEC", which is a boot sector

    File type is independent of the "extension", but just a marker for an auto-execution (firstmost PRG file will be
    auto-run). If your file is neither PRG nor TXT, use BIN.
    Operation system may choose to ignore this feature and handle the "extension" by itself