Desklink/TS-DOS Directory Access: Difference between revisions
| Line 126: | Line 126: | ||
|- | |- | ||
| 6 bytes | | 6 bytes | ||
| "& | | "<>" | ||
| 18 (decimal) bytes | | 18 (decimal) bytes | ||
| "F" | | "F" | ||
Revision as of 21:31, 10 December 2008
TS-DOS Directory Management Extensions Programmer's Guide
By Kenneth D. Pettit
Overview
TS-DOS was developed as an alternative for accessing the TPDD and TPDD-2 drives from the Tandy and NEC line of laptops (Model 100, 102, 200 and PC-8201a). As part of the design, when used with the companion "DeskLink" PC program, TS-DOS adds the ability to create and manage a directory structure on the target media. This same directory access extension is also built into the NADSBox SD card reader and allows navigation and access of the FAT directory structure on the media card. The extensions were discovered by reverse engineering the communication between a Model 102 and Desklink (running on an HP 200LX) and between TS-DOS and a TPDD-1 using an HP 4951B serial protocol analyzer. This document describes the TS-DOS directory management extensions (DME) and is, to my knowledge, a complete description of the protocol.
Protocol Structure
History
The TPDD-1 supported two modes of operation for accessing data on the floppy disc - an "Operational" mode and an "FDC Emulation" mode. Each of these modes have a very different command structure and are well documented in the TPDD-1 reference manual. The FDC Emulation mode was used for direct sector access of the data stored on the disc. Neither the TPDD-2 nor Desklink support the FDC Emulation mode and instead add sector access commands in Operational mode to provide the same functionality.
Basic premise for extension addition
The directory management extensions in TS-DOS are implemented partially using commands to support the FDC Emulation mode, and partially using a targeted file extension ("<>") in operational mode commands to denote references to a directory or subdirectory on the media. The FDC Emulation mode commands are used to identify if the client supports DME and the "<>" extension is used to specify target directories for creation, deletion or navigation.
Request Format
Both FDC Emulation requests and Operational mode requests are issued by TS-DOS, although only a single FDC Emulation mode request is used. FDC Emulation requests consist of a single ASCII character with one or more ASCII arguments followed by a carriage return (0Dh). Operational mode requests consist of a Preamble of ZZ (5Ah 5Ah), followed by a Request ID byte, a Payload Length byte, 0 or more payload bytes, terminated by a checksum.
All values are shown as hexadecimal. ASCII character strings are enclosed with quotation marks. The quotation marks are not part of the command or response.
Response Format
In operational mode, the reponse format is identical to the request format, except that no preamble is sent. In FDC Emulation mode, the reponse format varies depending on the command and the client. Specific details regarding FDC Emulation mode responses will be described as needed.
Client discovery
Since TS-DOS must operate with with various clients, and since not all clients follow the same protocol, it must determine if the client is capable of supporting DME. This is done by sending an FDC Emulation mode command to go into operational moded ("M1"), followed by an operational mode command to go into FDC Emulation mode. For this operational mode sequence, TS-DOS actually terminates the command with a carriage return (0Dh) which isn't part of the standard operational mode protocol. The following two commands are sent:
Directory Management Extensions Request (DMEReq)
| "M1" | 0D |
|
0D |
For a client that supports FDC Emulation mode, the standard response for both commands is no response. If the client does not respond to either command, or responds with an error message, then TS-DOS knows the client does not support DME.
If the client does support DME, then after the final carriage return (0Dh), it shall reply with a standard operational mode response. The response ID must be 12h and the payload field must be 11 bytes long and contain the name of the current directory, or at least the lowest level name in the tree, as shown below. The name should be 6 characters long and should be terminated with ".<>",20h. Names shorter than 6 characters should be padded with spaces before the ".<>",20h extension.
TS-DOS will display the directory name reported in the DMEResp payload in the upper right corner of the display in reverse video characters. If the current directory is the root "/" directory, then the client should return "ROOT .<> " in the payload filed as a standard, although any name could be provided. TS-DOS will send the DMEReq sequence multiple times including when it has requested a directory change operation. This provides a way of reporting the new subdirectory name for display in the TS-DOS title bar.
Directory Management Extensions Response (DMEResp)
| Response ID | Payload Length | Payload | Checksum | ||||||
| 12 | 0B |
|
Checksum |
Directory reporting from Client
The client device (Desklink, NADSBox, etc.) should use the receipt of a DMEReq as an indication to provide directory and subdirectory information to TS-DOS. If the DMEReq sequence is not received, then the client is communicating with a DOS that does not support DME, such as TEENY or FLOPPY, etc. Directory information is reported using the same protocol as regular files using the Directory Reference Request with the exception that the extension is reported as "<> ". Directory Reference Requests are part of the standard TPDD-1 and TPDD-2 protocol and can refer to a specific directory entry, or the first, next or previous entry in the directory. For filename discovery, the "first", "next" or "previous" search forms are used, and the filename is all 00h.
Directory Reference Request (DRReq)
| Preamble | Request ID | Payload Length | Payload | Checksum | ||||||
| 5A 5A | 00 | 1A |
|
Checksum |
When DME support has been established, the client reports directory information by responding to the DRReq sequence with a Directory Reference Response (DRResp) packet with the filename field containing the directory name in 6.2 filename format. The directory name should be 6 characters or less with space padding and the 2 character extension must be set to "<>". TS-DOS uses the "<>" extension to identify the entry as a directory. When the client is reporting file / directory entries for a directory other than the root, it should provide a mechanism for navigating to the parent directory. In both DeskLink and NADSBox, this is done by reporting the first entry of a subdirectory as "PARENT.<>". The number of Free Sectors on the media should be a single byte with the value 80H or less. Sectors in the TPDD protocol are 1280 bytes in length.
Directory Reference Response (DRResp)
| Response ID | Payload Length | Payload | Checksum | |||||
| 11 | 1C |
| ||||||
| 6 bytes | "<>" | 18 (decimal) bytes | "F" | 00 | # Sectors |
| Checksum |
Change Directory requests from TS-DOS
When the user navigates the cursor to a directory entry that has the "<>" extension and pressed Enter, TS-DOS will perform a Directory Change operation to naviagte to that directory. This is accomplished by sending a Change Direcotry Reference Request (CDRReq) followed by a standard Open File Request and then a Close File Request. The CDRReq packet is the same as a standard DRReq packet except the filename extension is set to "<>".
Change Directory Reference Request (CDRReq)
| Preamble | Request ID | Payload Length | Payload | Checksum | ||||||||||
| 5A 5A | 00 | 1A |
|
Checksum |
The client should respond to the CDRReq packet with a DRResp response packet containing the same directory name that was passed in the CDRReq. The client should save the directory name and expect to receive a subsequent Open File Request. When the Open File Request is received, the client should process it as a Change Directory operation to the directory specified in the CDRReq packet and return a standard Normal Response Packet (Id = 12H) with the appropriate error code. If the directory name matches the special name given for the parent directory ("PARENT.<>"), then the client should change to the parent of the current directory. The the client should then expect a Close File Request and respond as usual.
Checksum Algorithm
Total = Sum of all bytes from TypeID..Last byte of Payload
Checksum = (Total & FFh) XOR FFh
