
                               XCTest 0.13 beta



  This software allows you to easily test PC parallel ports  and  X1541-series
cables. For the latest release, visit http://sta.c64.org/scextprg.html.

  For more information on the X1541-series cables, see their central  page  at
http://sta.c64.org/xcables.html and the subpages below it.

  WARNING: This documentation is for complete beginners! It tries to  describe
and explain everything very carefully so that you  don't  just  do  test  but,
actually, understand what you're doing. Therefore,  you're  also  expected  to
take time to read everything very  carefully!  You  may  want  to  print  this
documentation so that you can have it handy any time.

  Note: This documentation is meant to be viewed with a monospace font, in IBM
code page 437 (US default for DOS). With a proportional  font,  drawings  will
fall apart; with other code pages, including  but  not  limited  to  DOS  85x,
Windows 125x and ISO 8859-x, some characters will look strange. You might want
to view this file in a text-based software rather than one  with  a  graphical
user interface. Obviously, this paragraph does not apply to the HTML  form  of
the document.



  0.  Table of contents

  1.  Usage
  2.  Configuration
  3.  Testing port behavior
  4.  Testing voltage levels
  5.  Reports
  6.  History
  7.  Current limitations
  8.  To do
  9.  Copyright and legal issues
  10. The author



  1.  Usage

  It is highly recommended that you  use  this  software  on  a  Pentium-class
machine. For the reasons and how to make the software work on  an  older  286,
386 or 486 machine, see below.

  Use plain DOS. The DOS shell of any Windows, OS/2 or the GNU/Linux dosemu is
not good enough because the host operating system may  filter  port  activity.
You may want to create a DOS boot disk and boot your PC with it if  you  don't
have DOS installed on your hard disk. If you really want to try  the  software
under Windows NT/2000/XP then download  the  latest  Windows NT/2000/XP  tweak
package from The Star Commander  homepage  at  http://sta.c64.org/sc.html  and
force compatibility mode (see below).

  Launch the software. A menu  will  appear.  Configuration  options  are  the
following:

  - Parallel ports. It lists  the  three  standard  parallel  ports  that  are
    detected as LPT1 to LPT3 by your BIOS plus two additional slots  that  you
    can fill in to use hardware that your BIOS doesn't detect for some reason.
    If the port address falls into a valid interval then it is displayed after
    the port name, in hexadecimal. Also, if detecting port  modes  is  enabled
    (see below) then the mode of the port is displayed after the port address;
    if the mode is unknown (not detected yet) then '???' is  displayed.  If  a
    port address is detected to be something other than a parallel  port  then
    neither its address nor its mode is displayed.

  - Detect port modes. Enable to have the mode  of  parallel  ports  detected.
    Known modes are SPP, PS/2, EPP and ECP. Beware, enabling this  option  may
    cause strange behavior on certain PC's, including lockups or the  parallel
    port falling into an unusable state from which it can only recover  during
    a hard reset (not Ctrl-Alt-Del, rather the separate RESET  button  on  the
    front of your PC).

  - Serial cable. This shows the type of the serial  cable.  Note  that,  upon
    startup, the serial cable type is intentionally  unset  so  that  you  are
    forced to manually select a valid serial  cable  type  before  continuing.
    Below the cable type, that parallel port is displayed to which  the  cable
    is connected.

  - Logic analyzer. Tells whether input state histories are in logic  analyzer
    mode or not. See below for more details.

  The hotkey for each option is displayed to the left of  the  option  itself.
Valid hotkeys are the following:

  - Esc: Exit the software.

  - A, C, D, R: Toggle the state of the Atn, Clock, Data or Reset output line,
    respectively.

  - X, E, M, B: Set the type of the serial cable to X1541, XE1541,  XM1541  or
    XA1541, respectively.

  - 4, 5: Set the port address of the additional parallel  port  slots.  Enter
    the port address in hexadecimal notation.

  - T: Toggle 'Detect port modes'.

  - L: Toggle 'Logic analyzer'.

  - S: Select the parallel  port  that  the  serial  cable  is  connected  to.
    Actually, it cycles through the five available parallel port slots.

  - +, -: Increase/decrease input sampling frequency. More on this later.

  You can also specify parameters on the command line in the form of

  XCTEST [[-|/]<options>]

  Valid command line parameters are similar to the hotkeys:

  - COMPAT: Force compatibility mode; do not use interrupts and do  not  touch
    the system timers either. This must  be  the  very  first  option  on  the
    command line!

  - X, E, M, B: Set the type of the serial cable to X1541, XE1541,  XM1541  or
    XA1541, respectively.

  - 4xxxx, 5xxxx: Set the port address of the additional parallel port  slots.
    Specify the port address in hexadecimal notation.

  - T: Toggle 'Detect port modes'.

  - L: Toggle 'Logic analyzer'.

  - Sx: Select the parallel port  that  the  serial  cable  is  connected  to.
    Specify the parallel port slot, between 1 and 5.

  - +, -: Increase/decrease input sampling frequency. More on this later.

  Parameters may begin with an optional  hyphen  or  slash;  for  option  '-',
obviously, a hyphen or slash must be prepended. Parameters  are  processed  in
the order of their appearance on the  command  line.  Invalid  parameters  are
ignored silently.



  2.  Configuration

  The suggested order of configuring is the following:

  1. If you wish to use a non-standard parallel port then put its port address
     into the first extra slot.

  2. If you want to see the modes of all available parallel ports then  enable
     'Detect port modes'.

  3. Set the parallel port for the serial cable.

  4. If needed, change sampling frequency.

  5. Set the type of the serial cable that is connected to the port you've set
     in the step 3.

  If you use command line parameters to preconfigure the software, you  should
specify the parameters in  this  suggested  order.  If  you  are  running  the
software in GNU/Linux dosemu or the DOS shell of Windows NT/2000/XP,  you  may
want force compatibility mode, in case you experience long delays or lockups.

  Upon setting the serial cable type, its parallel port is  reset  to  default
values and all four output lines are reset to high. Also, whenever you  change
the serial cable type or the parallel port it is connected  to,  the  parallel
port is reset again.

  Along with the current state of the output lines, the current state  of  the
input lines are displayed, as well. For low-level testing,  try  toggling  the
output lines and see how the input lines react to that. See the  next  chapter
on suggested tests.

  Because there may be jitter effects (more on this  later)  on  the  parallel
port, a history is also recorded for all four  input  lines.  Every  time  the
state of an input line changes, not only its current state is displayed in the
upper box but also its last few states in the lower box.

  In the input line histories, all entries consist of a counter and  a  state,
in the form '<counter>*<state>'. The counter tells how many clock  ticks  have
passed while the input line was in that state. Whenever the  software reads  a
different state on that input line, a new entry is created in the history  and
the counter reset to zero. The counter never flows over, it stops at a maximum
value of 99999. The most recent state of the input  line,  which  matches  the
current state in the upper box, is the leftmost entry in the history, the  one
where the counter keeps running constantly. As you move to the right, you  see
older and older states in the entries.

  In compatibility mode, the counters  will  show  improper  values  as  their
frequency is not fixed; they are updated by a simple loop instead. In  change,
no delays or lockups will occur and you will be able to  do  the  basic  tests
that do not require fine timing or time measurement.

  Input line histories have two modes:

  - Continuous mode. Changes to the configuration and the states of the output
    lines don't affect the history directly. The history is updated only  when
    the state of the respective input line changes.

  - Logic analyzer mode. Whenever you change the configuration or  toggle  any
    of the output lines, this event resets the history of all input lines.  In
    the oldest (rightmost) entry, you can see the original state - that before
    the event - in the form '... <state>'. Newer entries (towards  left)  show
    the state changes, along with timing, since the event. In this  mode,  you
    can measure the reaction time of the input lines to changes of the  output
    lines.

  By default, the software has a sampling frequency of 10 kHz which  means  it
checks for changes on the parallel port every 100 microseconds. This frequency
should work for all the tests below. However, if you want to  experiment,  you
can change the frequency with the appropriate hotkeys (see above). In the  box
frame, the frequency and the clock tick length are both displayed.

  The lower limit for the sampling frequency is 20 Hz because the  timer  chip
can't provide lower resolution. The upper limit  is  100  kHz  because,  at  a
higher frequency, interrupts would occur more often than the interrupt service
routine can handle; it would cause the PC to, effectively, lock up,  executing
nothing else than overlapping interrupts.

  For the reasons above, if you want to do some fine timing  tests,  you  will
definitely need a Pentium-class machine - and one as fast as possible at that.
And use the highest sampling frequency that your machine can work with. On the
other hand, if you want to use an old 286, 386 or 486  machine  then  you  may
need to lower the sampling frequency, in case the default locks  your  machine
up.

  When measuring reaction times, keep in mind that counter values are relative
to the sampling frequency. E.g. if sampling runs at 10 kHz, a clock tick takes
100 microseconds, therefore, a counter value of 123 means 123 *  100  =  12300
microseconds, that is, 12.3 milliseconds. On the other  hand,  at  a  sampling
frequency of 100 kHz, a clock tick takes only 10  microseconds,  therefore,  a
counter value of 123 means only 1230 microseconds, that is, 1.23 milliseconds.
Vice versa, an interval of 12.3 milliseconds will be displayed  as  a  counter
value of 1230 at a sampling frequency of 100 kHz and as 123  at  10  kHz.  The
general formula is: "Time interval" = "Counter value" * "Clock tick length".



  3.  Testing port behavior

  The behavior of the parallel port depends on the following circumstances:

  1. The serial cable type configured in the software.

  2. Whether a serial cable is connected to the parallel port or not;  if  so,
     what type of serial cable it is.

  3. Whether a switched on Commodore drive is on the other end of  the  serial
     cable or not.

  If you connect a Commodore drive then connect this  drive  only  to  the  PC
parallel port. Don't  daisy  chain  other  Commodore  drives,  peripherals  or
machines. Also, remove dongles, printer port switches and any  other  hardware
that may filter data transfer via the  parallel  port.  The  drive  should  be
turned on and left alone after reset. Test the drive, with  a  real  Commodore
machine, prior to these tests.

  GROUP 1. No serial cable is connected to the parallel port. Correct parallel
port behavior is the following:

  - PORT-X. X1541 cable configured; no cable connected. All  four  inputs  are
    the same as the respective output.

  - PORT-XE. XE1541 cable configured; no cable connected. All four inputs  are
    constant high.

  - PORT-XM. XM1541 cable configured; no cable connected. All four inputs  are
    constant high.

  - PORT-XA. XA1541 cable configured; no cable connected. All four inputs  are
    constant high.

  GROUP 2. A serial cable is connected to the parallel port. There's no  drive
on the other end of the serial cable; or there is a drive connected but it  is
switched off.

  If you have configured the correct serial  cable  type  then  parallel  port
behavior is the following:

  - CABLE-X. X1541 cable configured; X1541 cable connected; no drive. All four
    inputs are the same as the respective output.

  - CABLE-XE. XE1541 cable configured; XE1541 cable connected; no  drive.  All
    four inputs are the same as the respective output.

  - CABLE-XM. XM1541 cable configured; XM1541 cable connected; no  drive.  All
    four inputs are the same as the respective output.

  - CABLE-XA. XA1541 cable configured; XA1541 cable connected; no  drive.  All
    four inputs are the same as the respective output.

  If you have misconfigured the serial cable type then parallel port  behavior
is the following:

  - CABLE-X/XE. X1541 cable configured; XE1541 cable connected; no drive.  All
    four inputs are the same as the respective output.

  - CABLE-X/XM. X1541 cable configured; XM1541 cable connected; no drive.  All
    four inputs are the same as the respective output.

  - CABLE-X/XA. X1541 cable configured; XA1541 cable connected; no drive.  All
    four inputs are the same as the respective output.

  - CABLE-XE/X. XE1541 cable configured; X1541 cable connected; no drive.  All
    four inputs are constant high.

  - CABLE-XE/XM. XE1541 cable configured; XM1541 cable  connected;  no  drive.
    All four inputs are the same as the respective output.

  - CABLE-XE/XA. XE1541 cable configured; XA1541 cable  connected;  no  drive.
    All four inputs are the opposite of the respective output.

  - CABLE-XM/X. XM1541 cable configured; X1541 cable connected; no drive.  All
    four inputs are constant high.

  - CABLE-XM/XE. XM1541 cable configured; XE1541 cable  connected;  no  drive.
    All four inputs are the same as the respective output.

  - CABLE-XM/XA. XM1541 cable configured; XA1541 cable  connected;  no  drive.
    All four inputs are the opposite of the respective output.

  - CABLE-XA/X. XA1541 cable configured; X1541 cable connected; no drive.  All
    four inputs are constant high.

  - CABLE-XA/XE. XA1541 cable configured; XE1541 cable  connected;  no  drive.
    All four inputs are the opposite of the respective output.

  - CABLE-XA/XM. XA1541 cable configured; XM1541 cable  connected;  no  drive.
    All four inputs are the opposite of the respective output.

  GROUP 3. A serial cable is connected to the parallel port. There's  a  drive
on the other end of the serial cable and it is switched on. You configured the
proper serial cable type (otherwise you will get very strange results).

  Beware, all tests below assume that all four outputs are set to high at  the
beginning. Keep in mind that if  an  output  line  is  set  to  low  then  the
corresponding input line will also remain low, no matter what the drive  wants
to send back via that line.

  - DRIVE-LOOP. Set all outputs to high. Set Atn output to low. Atn input goes
    low. Set Atn output back to high. Atn input goes back high.  Do  the  same
    with all the other outputs - remember  to  start  each  subtest  with  all
    outputs high - to check whether the PC can see its own low  output  signal
    coming back via the respective input line.

  - DRIVE-RESET. Set all outputs to high. Set Reset output to low. Clock, Data
    and Reset input will go  low  while  the  drive  is  stuck  in  its  reset
    sequence. Set Reset output to high. Clock and Reset input will go high  at
    once. Data input is still low: the drive  is  signalling  the  serial  bus
    master that it's busy at the moment. As soon as the  drive  completes  its
    reset sequence (watch the "Drive" LED), Data input will also go high: this
    is the drive's "ready to go" signal. Note that it is  not  recommended  to
    keep resetting the drive for more than only a few seconds because  it  may
    stress the circuitry.

  - DRIVE-DETECT. Set all outputs to high. Set Clock output to low. Toggle Atn
    output. Not only Atn input will be the same as Atn output but Data  input,
    as well. This behavior of the Data line is the standard  device  detection
    method of Commodore machines and peripherals.

  - DRIVE-DETECT-INV. Set all outputs to high. Set Atn  output  to  low,  then
    Clock output to low, in this order. Toggle Atn output. Atn input  will  be
    the same as Atn output and Data input will be the opposite.

  - DRIVE-DETECT-COMBO. Combine the previous two tests.  Set  all  outputs  to
    high. Set Clock output to low, then Atn output to low, in this order. Data
    input will go low. Set Clock output to high. Data input will go high.  Set
    Clock output to low, then Atn output to high, in this  order.  Data  input
    will go low. Set Clock output to high. Data input will go high.

  - DRIVE-DETECT-JITTER. For this test, you should have  the  keyboard  repeat
    rate set to maximum. Execute the DOS command "mode con rate=32 delay=1" to
    accomplish that. Even if Clock output is set to high, toggling Atn  output
    will make the drive reply with a short burst of Data input low.  Keep  'A'
    pressed so that the software toggles Atn output as fast as  possible.  You
    should see Data input flicker to low for a very short period of  time  and
    then back to high. Also, the history for Data input will clearly show  you
    the effect, at a  high  resolution  (unless  you  have  set  the  sampling
    frequency to a too low value).
    Interestingly enough, when changing Atn output to  high,  you  can  see  a
    single jitter: Data input goes high-low-high; when changing Atn output  to
    low, there's a double jitter: Data input goes high-low-high-low-high.

  If any of the first five tests failed, this  means  the  PC  can't  see  the
replies of the drive. Either the cable is faulty or it is not compatible  with
the current mode of your parallel port.

  If you're not sure about whether your cable is assembled properly then go to
http://sta.c64.org/xcables.html, see the appropriate cable  construction  page
below it and check your cable against the circuit diagrams. Make sure that you
understand which side the connectors and plugs are viewed from on the  circuit
diagrams.

  To change the mode of your parallel port:

  - For a separate parallel port card or an I/O controller card, rejumper it.

  - For an integrated parallel port, enter the  "Integrated peripherals"  menu
    in your BIOS setup. If you don't find a menu called like  that  then  find
    a menu of a similar name or refer to the motherboard manual.



  4.  Testing voltage levels

  If your parallel port doesn't behave as expected then you might want to  dig
even deeper and test the outgoing voltage levels.

  CABLE-VOLTAGE. Configure the serial cable type in the software  and  connect
the proper serial cable to the parallel port. On the other end of  the  cable,
you can see the usual Commodore serial bus plug.  Don't  plug  this  end  into
anything, leave it unconnected. The following picture shows the plug as viewed
from its front side:

                                     Reset
                                       |
                                       V
                                 -----   -----
                                /     \_/     \
                               /  1         5  \ 
                    SrqIn --> |   o    6    o   | <-- Data
                              |        o        |
                              |   2         4   |
                      GND --> |   o    3    o   | <-- Clock
                               \       o       /
                                \             /
                                 -------------
                                       ^
                                       |
                                      Atn

  Note that this is not the solder side (the back side) of the plug.

  Grab a multimeter and set it to measure DC (direct current)  voltage;  don't
try measuring AC (alternating current)  voltage.  The  maximum  voltage  limit
should be set to around 10V-100V. A lower limit may damage the device, in case
your parallel port emits  a  significantly  higher  voltage,  for  some  weird
reason. A higher limit does no harm but the measurement will be less  precise.
Feel free to start with the highest limit available  on  your  multimeter  and
then go downwards, if needed.

  Touch one tip of the multimeter to the GND pin of the serial plug. With  the
other tip, touch each of the Atn, Clock, Data  and  Reset  pins.  The  voltage
level of all four pins should follow the  respective  output  state  that  the
software displays. The sign of the voltage  level  doesn't  matter:  0.1V  and
-0.1V are equivalent.

  For a low output state displayed by the  software,  your  multimeter  should
show a voltage close to 0V: between  0.0V  and  0.8V.  For  a  high  state,  a
voltage close to 5V should be displayed: between 2.8V and 5.0V. These are  the
standard TTL levels.

  If the voltage is outside the above mentioned intervals,  that  is,  between
0.8V and 2.8V, then both the Commodore drive and the PC may  read  garbage  on
that particular line. Beware, voltages close to the 0.8V and 2.8V  limits  may
also cause the same garbage  on  certain  hardware  that  doesn't  follow  the
specifications at hundred percent.

  DRIVE-VOLTAGE. You can also do measurements with  a  full  setup:  a  serial
cable connected to the parallel port, a drive attached to the other end of the
serial cable and the drive switched on.

  Connect the serial cable to the  parallel  port  and  configure  the  proper
serial cable type in the software. Plug the other end of the serial cable into
the Commodore drive. For the tests, you should use the second serial  port  of
the drive. The following picture shows the port as viewed from the rear of the
drive:

                                     Reset
                                       |
                                       V
                                 -----   -----
                                /     \_/     \
                               /  5         1  \ 
                     Data --> |   o    6    o   | <-- SrqIn
                              |        o        |
                              |   4         2   |
                      Clk --> |   o    3    o   | <-- GND
                               \       o       /
                                \             /
                                 -------------
                                       ^
                                       |
                                      Atn

  Note that this is a horizontal mirror of the other diagram above.

  Plug one tip of the multimeter into the GND hole of the  serial  port.  Plug
the other tip into each of the Atn, Clock, Data and Reset holes. If the tip is
too thick to fit into the holes then plug pieces of thick wire or  thin  nails
into the serial port and touch those instead with the tips. But be careful  to
not damage the hardware or cause short circuits.

  The voltage level of all four pins should follow the respective output state
that the software displays. For a low output state displayed by the  software,
your multimeter should show a voltage close to 0V: between 0.0V and 0.8V.  For
a high state, a voltage close to 5V should  be  displayed:  between  2.8V  and
5.0V.

  Beware, the voltage levels measured  in  a  full  setup  will  certainly  be
different from those measured when only a cable is connected to  the  parallel
port. However, they should still be within the limits, otherwise communication
between the PC and the Commodore drive will not work.



  5.  Reports

  If you have questions about this software, the tests or  your  test  results
then send a detailed report to the author's E-mail address below. Your  report
should contain, at least, the following information:

  1. Manufacturer and type of the motherboard of your PC.

  2. Manufacturer and type of the chipset on the I/O controller  card  or  the
     one integrated onto the motherboard.

  3. The type of your serial cable.

  4. Manufacturer and type of your Commodore  drive  (if  you  have  connected
     one).

  5. All configuration settings in the software. (In a later release, settings
     will be logged into a file automatically.)

  6. The code of the test you tried - it's in all capitals  in  front  of  the
     test description. (In a later  release,  input  line  histories  will  be
     logged into a file automatically.)

  7. Any other circumstances that you think to be important.

  Incomplete reports will not be replied to! Also, before reporting, make sure
that you have read this documentation carefully enough!



  6.  History

  0.01 alpha (2001-12-16):

  - First release, only for internal testing.

  0.02 alpha (2001-12-17):

  - New: Added display of Atn input, Reset output and Reset input.
  - New: Added the possibility to change Reset output.
  - New: Added the description of some more tests for full setups.

  0.03 alpha (2001-12-18):

  - Fix: Fixed a few typos and misunderstandable parts in the documentation.
  - Mod: Broke down the tests into all possible cases, creating groups.
  - New: Added the description of one more test for full setups.
  - New: Collected ideas into a "to do" section.
  - New: Numbered all sections and created a table of contents.

  0.04 alpha (2002-01-03):

  - Mod: Gave  descriptive  names  for  the  tests,  instead  of  having  them
         numbered. Also, regroupped them a bit.
  - Mod: Reworked input line reading: now it is done by a  separate  interrupt
         that occurs at a changeable frequency.  The  advantage  is  that  the
         input state display routine is not executed upon every read,  thus  a
         significantly higher sampling frequency can be achieved.
  - New: Added support for command line parameters.
  - New: Added history for input lines.
  - New: Added description on how to test voltage levels with full setups.

  0.05 alpha (2002-01-09):

  - Mod: Changed input line histories to make room for one more entry.
  - Mod: Internally, all input line histories now consist of much more entries
         than just the few being displayed on the screen. This is  needed  for
         logging the histories into a file.
  - Mod: Changed the default state for Clk output to high.
  - New: Added logic analyzer mode for input line histories.

  0.10 beta (2002-03-06):

  - First public release, no changes since 0.05 alpha.

  0.11 beta (2002-06-05):

  - Fix: Fixed a few typos and misunderstandable parts in the documentation.
  - Mod: Swapped chapters "History" and  "Current limitations",  to  make  the
         documentation similar to that of The Star Commander.
  - New: When running under Windows NT/2000/XP, the  "giveio"  and  "userport"
         drivers are initialized. For more information on these  drivers,  see
         the documentation of the Windows NT/2000/XP tweak package.

  0.12 beta (2002-08-11):

  - Fix: Fixed the description of the DRIVE-DETECT-COMBO test.
  - Mod: Removed code page-specific frame characters from the ASCII pictures.

  0.13 beta (2004-09-01):

  - New: Added compatibility mode for running the software in GNU/Linux dosemu
         or the DOS shell of Windows NT/2000/XP.



  7.  Current limitations

  Current known limitations and problems of the software are the following:

  - The software can only set output lines to high and low values and  display
    the states of input lines.

  - Only serial cables - X1541, XE1541, XM1541 and XA1541 - are supported.



  8.  To do

  The following functions are planned to be implemented, in  decreasing  order
of priority:

  - Logging initial configuration, configuration changes,  keypresses,  output
    line states and input line state histories into a file.

  - Automatic detection of serial cable type. Also, automatic tests  to  check
    whether the  serial  cable  is  working  correctly,  including  the  tests
    described above. Perhaps, automatic tests might be  built  with  a  simple
    scripting language. (This means integrating X1541Test into this software.)

  - Support for the additional parallel cables - XH15x1  and  XP15x1 - in  the
    software. Also, description of additional tests for these cables.

  - Real tests, including high-level communication with the  Commodore  drive.
    (This means integrating XCDetect into this software.)



  9.  Copyright and legal issues

  The source of this software is public domain and provided here "as is"  -  I
don't feel like commenting it more but if you have problems then feel free  to
ask me. If you derive your own software from the source or put a part  of  the
source into your own software, please, give me a credit and send a copy to me.



  10. The author

  If you're interested in some similarly useful utilities you can  contact  me
at sta@c64.org or visit my homepage at http://sta.c64.org.

  Joe Forster/STA
  1st September, 2004
