-*- DRAFT -*- -*- DRAFT -*- -*- DRAFT -*- -*- DRAFT -*- -*- DRAFT -*- This is a draft copy of a partially completed specification and is not for distribution! 1 Introduction This is a specification of the serial line protocol for the Tandy Disk Drive (TDD). This is the result of studying documents and programs on the Club 100 BBS. No representation as to the accuracy of the material herein is made. 2 Hardware Interface Communication takes place over a serial port running at 19,200bits/sec or 9,600 bits/sec. The CTS and RTS lines are used for handshaking. The host issues messages to the drive, and the drive responds with a message. A message from the host is always preceded by two 'Z' characters 3 Checksum A checksum is a simple addition. The bytes which are checksummed are simply added using 8-bit unsigned arithmetic and the resulting byte is appended to the message. When a message is received, its checksum is computed and compared to the checksum in the last byte; if they are equal, the message was received correctly. 4 FIND FILE A FIND FILE message has three forms: Find a specific file, initiate directory scan, and next file. 4.1 Message A FIND FILE message appears as shown below |<-------------------- checksummed data ------------------>| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 0 |len| F | F | F | F | F | F | . | E | E | E | | n | ck| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ \________________len bytes_______________________/ Z Literal "Z". Attention signal to drive. Two of these precede each message. 0 Hex 0, opcode for FIND FILE len Length of the remainder of the message, excluding the checksum. F Filename portion. 6 characters, padded with spaces to form a 6-character field. . Period. Must appear in position as shown. E Filename extension. Up to 3 characters. space The remaining space, up to the maximum number of bytes for the filename, 24, is padded with spaces. n Type of FIND FILE operation. 0 Return information on specific file shown. 1 Initiate directory scan; return first name in directory. 2 Next name in directory. ck Checksum. 4.2 Responses A successful FIND FILE returns a message as shown below. Note the field marked *. If the response is a valid file responding to a FIND FILE 1 or FIND FILE 2, this value will be the letter F. If the response is not a valid filename, because the directory is empty or the previous request delivered the last name in the directory, this value will be hex 0. |<------------------- checksummed data ------------------>| | | 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 <= byte 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |s|f|f|f|f|f|f|.|e|e|e| | | | | | | | | | | | | | |*|u|l|r|k| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ s = 17 (0x11) f = filename characters . = period e = extension characters * = 'F' or 0 if "last entry" indicator u = upper 8 bits of size l = lower 8 bits of size r = residual space (0..FF) or 80 k = checksum - 2 - If an error occurs, one of the standard error messages will be returned. Questions: Is there a notion of partial match? For FIND FILE 1, is the file name relevant or present? Is the file name padded out to the full 24-byte field or is it the shortest name that can be sent? 5 OPEN FILE An OPEN FILE message is as shown below. An OPEN FILE message is valid only if there is not already an open file (no more than one file at a time may be opened on the drive). If any file is already open, the error response 64 (IO Error) is returned. An attempt to open a file for output or append on a locked drive will generate an error response. 5.1 Message |<-------------------- checksummed data ------------------>| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 1 |len| F | F | F | F | F | F | . | E | E | E | | n | ck| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ Z Literal "Z". Attention signal to drive. Two of these precede each message. 1 1, opcode for OPEN FILE len Length of the remainder of the message, excluding the checksum. F Filename portion. 6 characters, padded with spaces to form a 6-character field. . Period. Must appear in position as shown. E Filename extension. Up to 3 characters. space The remaining space, up to the maximum number of bytes for the filename, 24, is padded with spaces. n Type of OPEN FILE operation. 1 Open for WRITE 2 Open for APPEND 3 Open for READ ck Checksum. 5.2 Responses If the file is opened successfully - 3 - || +---+---+---+ | 18| 0 | ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 0 Decimal 0, the successful completion code. ck Checksum for the message. If the file is not found || +---+---+---+ | 18| 16| ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 16 Decimal 0, 0x10, the file-not-found error code. ck Checksum for the message. If a file is already open, If the filename is an empty name || +---+---+---+ | 18| 64| ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 64 Decimal 64, 0x40, the I/O error code. ck Checksum for the message. If the disk is write-protected, and the open is for WRITE or APPEND || +---+---+---+ | 18| 80| ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 80 Decimal 80, 0x50, the write-protected error code. ck Checksum for the message. If the disk directory is full - 4 - || +---+---+---+ | 18| 96| ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 96 Decimal 96, 0x60, the disk full error code. ck Checksum for the message. Questions: Does open for APPEND require the file already exist, or is it created if it does not already exist? 6 CLOSE FILE |<------------------ checksummed data -------------------->| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 2 |len| F | F | F | F | F | F | . | E | E | E | | n | ck| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ Z Literal "Z". Attention signal to drive. Two of these precede each message. 2 2, opcode for CLOSE FILE len Length of the remainder of the message, excluding the checksum. F Filename portion. 6 characters, padded with spaces to form a 6-character field. . Period. Must appear in position as shown. E Filename extension. Up to 3 characters. space The remaining space, up to the maximum number of bytes for the filename, 24, is padded with spaces. n Type of CLOSE FILE operation. 1 ? 2 ? ck Checksum. Questions: What are the types of CLOSE operations? Only explicit tests for 1 and 2 appear in the code I've seen, but no explanation is given. Is the file name given at all in a CLOSE? Is a CLOSE connected to a NAME operation? - 5 - 6.1 Response A CLOSE request always succeeds, and responds as shown: || +---+---+---+ | 18| 0 | ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 0 Decimal 0, the successful completion code. ck Checksum for the message. Questions: Is it true that a close always succeeds? 7 READ 7.1 Message +---+---+---+---+--...--+---+ | Z | Z | 3 |len| | ck| +---+---+---+---+--...--+---+ Z Literal "Z". Attention signal to drive. Two of these precede each message. 3 3, opcode for READ. ck Checksum. 7.2 Response A succesful READ operation responds with a message containing up to 128 bytes of data. |<-------------------- checksummed data ------------------->| +---+---+---+---+---+---+--...--+---+---+---+---+---+---+---+---+ | 16|len| | ck| +---+---+---+---+---+---+--...--+---+---+---+---+---+---+---+---+ If there is no more data, the response is an end-of-file message: || +---+---+---+ | 18| 48| ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 48 Decimal 48, 0x30, the end-of-file code. - 6 - ck Checksum for the message. If there is any error, the response is || +---+---+---+ | 18| 64| ck| +---+---+---+ 18 Decimal 18, 0x12, the opcode for a response. 64 Decimal 64, 0x40, the I/O error code. ck Checksum for the message. 8 WRITE 9 Message |<-------------------- checksummed data ------------------>| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 4 |len| | ck| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ \__________________len data bytes________________/ Z Literal "Z". Attention signal to drive. Two of these precede each message. 4 4, opcode for WRITE. len Number of bytes which follow, to a maximum of 128 (0x80). ck Checksum. 10 Response If the operation is successful: || +---+---+---+ | 18| 0 | ck| +---+---+---+ If there is any I/O error: || +---+---+---+ | 18| 64| ck| +---+---+---+ - 7 - 18 Decimal 18, 0x12, the opcode for a response. 64 Decimal 64, 0x40, the I/O error code. ck Checksum for the message. If the disk is full: || +---+---+---+ | 18| 96| ck| +---+---+---+ 11 DELETE |<------------------- checksummed data ------------------->| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 5 |len| F | F | F | F | F | F | . | E | E | E | | n | ck| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ 12 FORMAT +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 6 |len| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ 13 STATUS OK +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 7 |len| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ 14 Unknown +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ | Z | Z | 8 |len| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+ 15 PROTOCOL - Disk drive asserts RTS * Computer sends 'Z' * Computer sends 'Z' - 8 - * Computer sends op * Computer sends len * Computer sends len*bytes * Computer sends checksum - Disk drive deasserts RTS - Disk drive performs operation - Disk drive transmits response * If computer does not receive response in a reasonable time, it aborts with a drive-not-ready message. - Repeat - 9 - Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . 1 2 Hardware Interface . . . . . . . . . . . . . . . . . . . . 1 3 Checksum . . . . . . . . . . . . . . . . . . . . . . . . . 1 4 FIND FILE . . . . . . . . . . . . . . . . . . . . . . . . 1 4.1 Message . . . . . . . . . . . . . . . . . . . . . . . 1 4.2 Responses . . . . . . . . . . . . . . . . . . . . . . 2 5 OPEN FILE . . . . . . . . . . . . . . . . . . . . . . . . 3 5.1 Message . . . . . . . . . . . . . . . . . . . . . . . 3 5.2 Responses . . . . . . . . . . . . . . . . . . . . . . 3 6 CLOSE FILE . . . . . . . . . . . . . . . . . . . . . . . . 5 6.1 Response . . . . . . . . . . . . . . . . . . . . . . 6 7 READ . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 7.1 Message . . . . . . . . . . . . . . . . . . . . . . . 6 7.2 Response . . . . . . . . . . . . . . . . . . . . . . 6 8 WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . 7 9 Message . . . . . . . . . . . . . . . . . . . . . . . . . 7 10 Response . . . . . . . . . . . . . . . . . . . . . . . . 7 11 DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 8 12 FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . 8 13 STATUS OK . . . . . . . . . . . . . . . . . . . . . . . . 8 14 Unknown . . . . . . . . . . . . . . . . . . . . . . . . . 8 15 PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . 8 i opcode for a response. 48