home *** CD-ROM | disk | FTP | other *** search
/ ftp.whtech.com / ftp.whtech.com.tar / ftp.whtech.com / club100 / ref / comand.tdd < prev    next >
Text File  |  2006-10-19  |  15KB  |  639 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.     -*- DRAFT -*- -*- DRAFT -*- -*- DRAFT -*- -*- DRAFT -*- -*- DRAFT -*-
  8.  
  9.       This is a draft copy of a partially completed specification and is
  10.       not for distribution!
  11.  
  12.  
  13.  1  Introduction
  14.  
  15.  
  16.  This is a specification of the serial line protocol for the Tandy Disk Drive
  17.  (TDD).  This is the result  of  studying  documents and programs on the Club
  18.  100 BBS.    No  representation  as to the accuracy of the material herein is
  19.  made.
  20.  
  21.  
  22.  2  Hardware Interface
  23.  
  24.  
  25.  Communication  takes  place  over a serial port running at 19,200bits/sec or
  26.  9,600 bits/sec.
  27.  
  28.  The CTS and RTS lines are used for handshaking.
  29.  
  30.  The  host  issues  messages  to  the  drive,  and the drive responds with  a
  31.  message.
  32.  
  33.  A message from the host is always preceded by two 'Z' characters
  34.  
  35.  
  36.  3  Checksum
  37.  
  38.  
  39.  A checksum is a simple addition.  The bytes which are checksummed are simply
  40.  added using 8-bit unsigned arithmetic and the resulting byte is  appended to
  41.  the  message.    When a message is received, its checksum  is  computed  and
  42.  compared to the checksum in the  last  byte;  if they are equal, the message
  43.  was received correctly.
  44.  
  45.  
  46.  4  FIND FILE
  47.  
  48.  
  49.  A  FIND  FILE  message has three  forms:  Find  a  specific  file,  initiate
  50.  directory scan, and next file.
  51.  
  52.  4.1  Message
  53.  
  54.  A FIND FILE message appears as shown below
  55.  
  56.          |<-------------------- checksummed data ------------------>|
  57.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  58.  | Z | Z | 0 |len| F | F | F | F | F | F | . | E | E | E |      | n | ck|
  59.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  60.                   \________________len bytes_______________________/
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  Z                 Literal "Z".  Attention  signal  to  drive.   Two of these
  68.                    precede each message.
  69.  
  70.  0                 Hex 0, opcode for FIND FILE
  71.  
  72.  len               Length of the  remainder  of  the  message,  excluding the
  73.                    checksum.
  74.  
  75.  F                 Filename portion.  6  characters,  padded  with  spaces to
  76.                    form a 6-character field.
  77.  
  78.  .                 Period.  Must appear in position as shown.
  79.  
  80.  E                 Filename extension.  Up to 3 characters.
  81.  
  82.  space             The remaining space, up to the maximum number of bytes for
  83.                    the filename, 24, is padded with spaces.
  84.  
  85.  n                 Type of FIND FILE operation.
  86.  
  87.                    0    Return information on specific file shown.
  88.  
  89.                    1    Initiate   directory  scan;  return  first  name   in
  90.                         directory.
  91.  
  92.                    2    Next name in directory.
  93.  
  94.  ck                Checksum.
  95.  
  96.  4.2  Responses
  97.  
  98.  A successful  FIND  FILE  returns  a message as shown below.  Note the field
  99.  marked *.  If the response is a valid file responding to a  FIND  FILE  1 or
  100.  FIND FILE 2, this value will be the letter F.   If  the  response  is  not a
  101.  valid  filename,  because  the  directory  is empty or the previous  request
  102.  delivered the last name in the directory, this value will be hex 0.
  103.  
  104.  |<------------------- checksummed data ------------------>|
  105.  |                                                         |
  106.                       1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2  <= byte
  107.   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
  108.  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  109.  |s|f|f|f|f|f|f|.|e|e|e| | | | | | | | | | | | | | |*|u|l|r|k|
  110.  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  111.  s = 17 (0x11)
  112.  f = filename characters
  113.  . = period
  114.  e = extension characters
  115.  * = 'F' or 0 if "last entry" indicator
  116.  u = upper 8 bits of size
  117.  l = lower 8 bits of size
  118.  r = residual space (0..FF) or 80
  119.  k = checksum
  120.  
  121.  
  122.  
  123.  
  124.                                     - 2 -
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  If an error occurs, one of the standard error messages will be returned.
  132.  
  133.  Questions: Is there a notion of partial match?  For FIND FILE 1, is the file
  134.  name  relevant or present?  Is the file name padded out to the full  24-byte
  135.  field or is it the shortest name that can be sent?
  136.  
  137.  
  138.  5  OPEN FILE
  139.  
  140.  
  141.  An OPEN FILE message is  as shown below.  An OPEN FILE message is valid only
  142.  if there is not already an open file (no more than one file at a time may be
  143.  opened on the drive).  If any file is already open,  the  error  response 64
  144.  (IO Error) is returned.  An attempt to open a file for output or append on a
  145.  locked drive will generate an error response.
  146.  
  147.  5.1  Message
  148.  
  149.          |<-------------------- checksummed data ------------------>|
  150.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  151.  | Z | Z | 1 |len| F | F | F | F | F | F | . | E | E | E |      | n | ck|
  152.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  153.  
  154.  Z                 Literal "Z".  Attention  signal  to  drive.   Two of these
  155.                    precede each message.
  156.  
  157.  1                 1, opcode for OPEN FILE
  158.  
  159.  len               Length of the  remainder  of  the  message,  excluding the
  160.                    checksum.
  161.  
  162.  F                 Filename portion.  6  characters,  padded  with  spaces to
  163.                    form a 6-character field.
  164.  
  165.  .                 Period.  Must appear in position as shown.
  166.  
  167.  E                 Filename extension.  Up to 3 characters.
  168.  
  169.  space             The remaining space, up to the maximum number of bytes for
  170.                    the filename, 24, is padded with spaces.
  171.  
  172.  n                 Type of OPEN FILE operation.
  173.  
  174.                    1    Open for WRITE
  175.  
  176.                    2    Open for APPEND
  177.  
  178.                    3    Open for READ
  179.  
  180.  ck                Checksum.
  181.  
  182.  5.2  Responses
  183.  
  184.  If the file is opened successfully
  185.  
  186.  
  187.  
  188.                                     - 3 -
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  |<cksum>|
  196.  +---+---+---+
  197.  | 18| 0 | ck|
  198.  +---+---+---+
  199.  
  200.  18                Decimal 18, 0x12, the opcode for a response.
  201.  
  202.  0                 Decimal 0, the successful completion code.
  203.  
  204.  ck                Checksum for the message.
  205.  
  206.  If the file is not found
  207.  
  208.  |<cksum>|
  209.  +---+---+---+
  210.  | 18| 16| ck|
  211.  +---+---+---+
  212.  
  213.  18                Decimal 18, 0x12, the opcode for a response.
  214.  
  215.  16                Decimal 0, 0x10, the file-not-found error code.
  216.  
  217.  ck                Checksum for the message.
  218.  
  219.  If a file is already open, If the filename is an empty name
  220.  
  221.  |<cksum>|
  222.  +---+---+---+
  223.  | 18| 64| ck|
  224.  +---+---+---+
  225.  
  226.  18                Decimal 18, 0x12, the opcode for a response.
  227.  
  228.  64                Decimal 64, 0x40, the I/O error code.
  229.  
  230.  ck                Checksum for the message.
  231.  
  232.  If the disk is write-protected, and the open is for WRITE or APPEND
  233.  
  234.  |<cksum>|
  235.  +---+---+---+
  236.  | 18| 80| ck|
  237.  +---+---+---+
  238.  
  239.  18                Decimal 18, 0x12, the opcode for a response.
  240.  
  241.  80                Decimal 80, 0x50, the write-protected error code.
  242.  
  243.  ck                Checksum for the message.
  244.  
  245.  If the disk directory is full
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.                                     - 4 -
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  |<cksum>|
  260.  +---+---+---+
  261.  | 18| 96| ck|
  262.  +---+---+---+
  263.  
  264.  18                Decimal 18, 0x12, the opcode for a response.
  265.  
  266.  96                Decimal 96, 0x60, the disk full error code.
  267.  
  268.  ck                Checksum for the message.
  269.  
  270.  Questions: Does open for APPEND require the file  already  exist,  or  is it
  271.  created if it does not already exist?
  272.  
  273.  
  274.  6  CLOSE FILE
  275.  
  276.  
  277.          |<------------------ checksummed data -------------------->|
  278.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  279.  | Z | Z | 2 |len| F | F | F | F | F | F | . | E | E | E |      | n | ck|
  280.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  281.  
  282.  Z                 Literal "Z".  Attention  signal  to  drive.   Two of these
  283.                    precede each message.
  284.  
  285.  2                 2, opcode for CLOSE FILE
  286.  
  287.  len               Length of the  remainder  of  the  message,  excluding the
  288.                    checksum.
  289.  
  290.  F                 Filename portion.  6  characters,  padded  with  spaces to
  291.                    form a 6-character field.
  292.  
  293.  .                 Period.  Must appear in position as shown.
  294.  
  295.  E                 Filename extension.  Up to 3 characters.
  296.  
  297.  space             The remaining space, up to the maximum number of bytes for
  298.                    the filename, 24, is padded with spaces.
  299.  
  300.  n                 Type of CLOSE FILE operation.
  301.  
  302.                    1    ?
  303.  
  304.                    2    ?
  305.  
  306.  ck                Checksum.
  307.  
  308.  Questions: What are the types of CLOSE operations?  Only explicit  tests for
  309.  1 and 2 appear in the code I've seen, but no explanation is given.    Is the
  310.  file name given at all in a CLOSE? Is a CLOSE connected to a NAME operation?
  311.  
  312.  
  313.  
  314.  
  315.  
  316.                                     - 5 -
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  6.1  Response
  324.  
  325.  A CLOSE request always succeeds, and responds as shown:
  326.  
  327.  |<cksum>|
  328.  +---+---+---+
  329.  | 18| 0 | ck|
  330.  +---+---+---+
  331.  
  332.  18                Decimal 18, 0x12, the opcode for a response.
  333.  
  334.  0                 Decimal 0, the successful completion code.
  335.  
  336.  ck                Checksum for the message.
  337.  
  338.  Questions: Is it true that a close always succeeds?
  339.  
  340.  
  341.  7  READ
  342.  
  343.  
  344.  7.1  Message
  345.  
  346.  +---+---+---+---+--...--+---+
  347.  | Z | Z | 3 |len|       | ck|
  348.  +---+---+---+---+--...--+---+
  349.  
  350.  Z                 Literal "Z".  Attention  signal  to  drive.   Two of these
  351.                    precede each message.
  352.  
  353.  3                 3, opcode for READ.
  354.  
  355.  ck                Checksum.
  356.  
  357.  7.2  Response
  358.  
  359.  A  succesful READ operation responds with a message  containing  up  to  128
  360.  bytes of data.
  361.  
  362.  |<-------------------- checksummed data ------------------->|
  363.  +---+---+---+---+---+---+--...--+---+---+---+---+---+---+---+---+
  364.  | 16|len|                                                   | ck|
  365.  +---+---+---+---+---+---+--...--+---+---+---+---+---+---+---+---+
  366.  
  367.  If there is no more data, the response is an end-of-file message:
  368.  
  369.  |<cksum>|
  370.  +---+---+---+
  371.  | 18| 48| ck|
  372.  +---+---+---+
  373.  
  374.  18                Decimal 18, 0x12, the opcode for a response.
  375.  
  376.  48                Decimal 48, 0x30, the end-of-file code.
  377.  
  378.  
  379.  
  380.                                     - 6 -
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  ck                Checksum for the message.
  388.  
  389.  If there is any error, the response is
  390.  
  391.  |<cksum>|
  392.  +---+---+---+
  393.  | 18| 64| ck|
  394.  +---+---+---+
  395.  
  396.  18                Decimal 18, 0x12, the opcode for a response.
  397.  
  398.  64                Decimal 64, 0x40, the I/O error code.
  399.  
  400.  ck                Checksum for the message.
  401.  
  402.  
  403.  8  WRITE
  404.  
  405.  
  406.  9  Message
  407.  
  408.  
  409.          |<-------------------- checksummed data ------------------>|
  410.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  411.  | Z | Z | 4 |len|                                                  | ck|
  412.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  413.                   \__________________len data bytes________________/
  414.  
  415.  Z                 Literal "Z".  Attention  signal  to  drive.   Two of these
  416.                    precede each message.
  417.  
  418.  4                 4, opcode for WRITE.
  419.  
  420.  len               Number of bytes which follow, to a maximum of 128 (0x80).
  421.  
  422.  ck                Checksum.
  423.  
  424.  
  425.  10  Response
  426.  
  427.  
  428.  If the operation is successful:
  429.  
  430.  |<cksum>|
  431.  +---+---+---+
  432.  | 18| 0 | ck|
  433.  +---+---+---+
  434.  
  435.  If there is any I/O error:
  436.  
  437.  |<cksum>|
  438.  +---+---+---+
  439.  | 18| 64| ck|
  440.  +---+---+---+
  441.  
  442.  
  443.  
  444.                                     - 7 -
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  18                Decimal 18, 0x12, the opcode for a response.
  452.  
  453.  64                Decimal 64, 0x40, the I/O error code.
  454.  
  455.  ck                Checksum for the message.
  456.  
  457.  If the disk is full:
  458.  
  459.  |<cksum>|
  460.  +---+---+---+
  461.  | 18| 96| ck|
  462.  +---+---+---+
  463.  
  464.  
  465.  11  DELETE
  466.  
  467.  
  468.          |<------------------- checksummed data ------------------->|
  469.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  470.  | Z | Z | 5 |len| F | F | F | F | F | F | . | E | E | E |      | n | ck|
  471.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  472.  
  473.  
  474.  12  FORMAT
  475.  
  476.  
  477.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  478.  | Z | Z | 6 |len|
  479.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  480.  
  481.  
  482.  13  STATUS OK
  483.  
  484.  
  485.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  486.  | Z | Z | 7 |len|
  487.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  488.  
  489.  
  490.  14  Unknown
  491.  
  492.  
  493.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  494.  | Z | Z | 8 |len|
  495.  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+--..--+---+---+
  496.  
  497.  
  498.  15  PROTOCOL
  499.  
  500.  
  501.      -  Disk drive asserts RTS
  502.  
  503.             *  Computer sends  'Z'
  504.             *  Computer sends  'Z'
  505.  
  506.  
  507.  
  508.                                     - 8 -
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.             *  Computer sends  op
  516.             *  Computer sends  len
  517.             *  Computer sends  len*bytes
  518.             *  Computer sends  checksum
  519.  
  520.      -  Disk drive deasserts RTS
  521.      -  Disk drive performs operation
  522.      -  Disk drive transmits response
  523.  
  524.             *  If computer does not receive response in a reasonable time, it
  525.                aborts with a drive-not-ready message.
  526.  
  527.      -  Repeat
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.                                     - 9 -
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.                                 Contents
  586.  
  587.  
  588.          1  Introduction . . . . . . . . . . . . . . . . . . . . . . . 1
  589.          2  Hardware Interface . . . . . . . . . . . . . . . . . . . . 1
  590.          3  Checksum . . . . . . . . . . . . . . . . . . . . . . . . . 1
  591.          4  FIND FILE  . . . . . . . . . . . . . . . . . . . . . . . . 1
  592.             4.1  Message . . . . . . . . . . . . . . . . . . . . . . . 1
  593.             4.2  Responses . . . . . . . . . . . . . . . . . . . . . . 2
  594.          5  OPEN FILE  . . . . . . . . . . . . . . . . . . . . . . . . 3
  595.             5.1  Message . . . . . . . . . . . . . . . . . . . . . . . 3
  596.             5.2  Responses . . . . . . . . . . . . . . . . . . . . . . 3
  597.          6  CLOSE FILE . . . . . . . . . . . . . . . . . . . . . . . . 5
  598.             6.1  Response  . . . . . . . . . . . . . . . . . . . . . . 6
  599.          7  READ . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
  600.             7.1  Message . . . . . . . . . . . . . . . . . . . . . . . 6
  601.             7.2  Response  . . . . . . . . . . . . . . . . . . . . . . 6
  602.          8  WRITE  . . . . . . . . . . . . . . . . . . . . . . . . . . 7
  603.          9  Message  . . . . . . . . . . . . . . . . . . . . . . . . . 7
  604.          10  Response  . . . . . . . . . . . . . . . . . . . . . . . . 7
  605.          11  DELETE  . . . . . . . . . . . . . . . . . . . . . . . . . 8
  606.          12  FORMAT  . . . . . . . . . . . . . . . . . . . . . . . . . 8
  607.          13  STATUS OK . . . . . . . . . . . . . . . . . . . . . . . . 8
  608.          14  Unknown . . . . . . . . . . . . . . . . . . . . . . . . . 8
  609.          15  PROTOCOL  . . . . . . . . . . . . . . . . . . . . . . . . 8
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.                                       i
  637.  opcode for a response.
  638.  
  639.  48