
        			  MAXDOC

                              Sept. 20, 1991

	  Test program for the Adaptec 1540A SCSI to AT host adapter


				  Jumpers

	1. Refer to the pamphlet shipped with the board for the
	    jumper locations.

	2. This program can be run on the Adaptec AHA1540A host 
	    adapter with the jumpers as shipped.

	3. If synchronous negotiation by the host is desired, jumper
	    the top pin pair on J1 of the host adapter.

	4. Set the SCSI ID as desired; it is shipped as 7.

	5. Disable the BIOS if you don't want to run as a DOS device
	    also, because otherwise the system may try to boot from
	    the host adapter.
	   But the program will run with the BIOS enabled also.

	6. The other jumpers need only be changed if there is a conflict
	    with something else in your system.



			     Starting the program

	1. Command line parameters may be either upper or lower case.

	2. Start the program by typing "MAXTEST".

	3. A command file may be called this way: "MAXTEST CMDS".

	4. A port may be selected by typing "MAXTEST CMDS -P".
	    A list of possible ports will be presented.
	    Choose the one that is set by the jumpers. [page 2-15]
	    Default is 330h; any other must be selected with -P.
	   If you already know the port number, you may type
	    "MAXTEST CMDS -P134" or whatever the port number is.
	   If the board is not jumpered to the selected port, the
	    program will tell you so and exit.
	   But this option allows running a system board and a test
	    board if desired.

	5. Monochrome may be forced with -M.  Usually this is not
	    necessary, since the program reads the system bytes to
	    self-configure.

	6. The only required parameter is "MAXTEST".
	    The others are optional and may be entered in any order.

				     1
				  MAXDOC  

				Philosophy

	This is an open-ended tester.  Since it is hard to predict which
	commands will be desired by the user, no attempt has been made to
	automate the command definition.

	But every attempt has been made to make the tester easy to use.

	1. Upper case or lower case entries are both treated equally.

	2. While editing SCSI commands and data, only entries that are
	      in range will be accepted.

	3. For almost all user commands, defaults are provided in 
	      brackets [ ]; just return will accept the default.

	4. When entering yes/no [Y/N] choices, anything but Y will be
	      interpreted as no.  

	5. When entering multiple byte user choices, backspace and
	      right and left arrow keys allow editing.  Return may be
	      hit anywhere in the entry, and the whole entry will be
	      accepted.  Escape will refuse the whole entry, changing
	      nothing.  This is useful if you decide you don't want to
	      execute this user command.

	6. Escape will get you out of almost anything except the 
	      program.

				     2
				  MAXDOC  

		   Special characteristics of the AHA1540A

	Reset: SCSI vs. host adapter

	  1. F3 and Z are identical: they execute both a host adapter
	      and a SCSI reset.  
	     THIS IS THE ONLY WAY TO FORCE A SYNCHRONOUS NEGOTIATION!

	  2. F8 executes a SCSI reset without a synchronous negotiation.
	      This is the way to force asynchronous transfers.
	     The host adapter still reports in F5 [report synchronous
	      negotiation results] that it is synchronous, but a logic
	      analyzer shows that it is asynchronous.

	  3. A SCSI reset from another source, including powering off
	      and on the drive under test, will also result in 
	      asynchronous transfers, unless the user executes a
	      board reset.


	Computer to host adapter interface

	  1. This program translates each displayed command into a
	      software structure.
	     When a command file is loaded, and at some other times,
	      a ripple can be seen running down the screen.
	     This occurs during the conversion of the text list of
	      SCSI commands to the corresponding structures.

	  2. Mailboxes-out are the way the host adapter finds out
	      which SCSI commands to execute.
	     Mailboxes-in tell the program which SCSI commands have
	      finished execution. 
	     There are 20 pairs of mailboxes: 20 out and 20 in.
	     Mailboxes can be displayed with Control M, or by hitting
	      return to stop looping commands.
	     00 in the first byte of any mailbox means the mailbox
	      is free [not in use].
	     01 in the first byte of a mailbox-out means that the
	      program has told the host adapter to execute the command
	      whose address is in that mailbox, but that the host
	      adapter has not yet done so.
	     01 in the first byte of a mailbox-in means good completion
	      of the command whose address is in that mailbox.
	     04 in the first byte of a mailbox-in = error completion.
	     This is mainly of use if the drive hangs, to tell which
	      commands have or have not finished.

	  3. Mailboxes in and out are matched by the address in them,
	      not by their number.  The "out" may be in mailbox 2,
	      while the "in" may be in maibox 17.

				     3
			   	   MAXDOC  

			    SCSI command editing

	1.  Control M [Modify] selects command editing.
	    A prompt will ask, Which command?
             Enter the command number [0 to 19].
	    The command being edited will be highlighted.
	    Arrow, home, end, and tab keys let you move around
	     in the commands. 

	2.  Only allowed choices are accepted, otherwise no change is
	     made in the command.

	3.  Editing starts at the far left byte of the selected command.
	     This byte is the SCSI opcode.
	    Enter the bytes as required for the SCSI command.
	     Any number of bytes may be entered up to 12.
	    If the appropriate value is already there, you may just
	     move past it.

	4.  Target ID and LUN [TARG ID, LN] may be entered as
	     appropriate: 0 - 7 are accepted.

	5.  Buffer [BUFFER #] is a letter: A, B, or D is accepted.
	     Buffers A and B are each 64K [addresses up to FFFFh].
	     D [double] selects both, giving one 128K buffer.

	6.  Buffer address [BUFFER ADDR] is the address where the data
	     will start reading or writing.
	    Any address in the buffer is accepted, but it must be hex.

	7.  Linked command [LNK CMD] tells to which command this
	     command will be linked.
	    For example: while editing command 1 you may link it to any
	     other command on the screen; just enter that command's
	     number [0 - 19].
	    But this field will be ignored unless the link bit is set
	     in the command's last byte [last byte = 01 or 03].

	8.  Command length [CMD LEN] defines the SCSI command length.
	    Commands with opcodes lower than 20h are treated as 6 byte 
	     commands; the rest are treated as 10 byte commands.
	    If the command length field = 0, default lengths are used.
	    If the default command length is not correct, enter the
	     length in the command length field in decimal.

	9.  Host and drive status [STATUS, HO, DR] and sense key, code,
	     and qualifier [SENSE KY, CD, QF] cannot be edited.
	    They are filled in by the program after command execution.

	10. You may arrow up or down to edit another command if desired.

	11. Return [Enter] or Escape completes SCSI command editing.
	     The command gets converted at this time.
	    If the number of data blocks is too big to fit in the buffer
	     defined, a message will appear at the bottom of the screen
	     telling you so.  When you hit a key to show you have read
	     the message, the data length field will get corrected to fit. 

				     4
				  MAXDOC  

				  Buffers

	1.  Two 64K data buffers are used by the program: A and B.
	    These buffers are identical.  You can do all the things
	     listed in the buffer menu equally well with either one.
	    The two buffers can be used as one by selecting D [double]
	     when editing a command.

	2.  A buffer can be wrapped up to 16 times by selecting
	     buffer wrap with Control W.
	    This is a little slower, and only the last wrap of data
	     can be compared.  It is recommended to use buffer wrap
	     only if you need longer transfers than will fit in 128K.
	    In some cases, buffer wrap hangs...it may not be the drive.

	3.  The buffer menu is a separate set of choices, entered by
	     R [Read] or W [Write] from the main menu [list of commands]
	     or from the main help menu [H].
	    R and W prompt you for which buffer [A or B].
	     Entering anything but B will choose buffer A.
	    The buffer will be displayed starting at address 0.

	4.  W [Write] puts the cursor at the top left buffer position
	     ready to edit the buffer.
	    R [Read] puts the cursor at the bottom of the screen 
	     waiting for a buffer menu choice.

	5.  H [Help] shows buffer menu choices with a little more
	     detail.
	    A very brief list of some buffer choices appears at the
	     bottom of the buffer screen.
	    Enter the first letter of your choice, either from the
	     buffer screen or from the buffer help menu.
	    Further prompts will appear asking for the parameters needed.

	6.  A [Address] displays current buffer at the address entered.
	     This is a way to jump around in the buffer.

	7.  B [Buffer] lets you choose which buffer to display at the
	     current address.

	8.  E [Edit] lets you edit the current buffer, starting at the 
	     top left position displayed.
	    Right, left, up, and down arrow keys may be used to move
	     around while editing.
	    Page Up and Page Down are also supported.
	    The buffers wrap at the end: addresses go from FFF0h to 0h.
	    Only hex characters are accepted.
	    An ASCII dump of printable characters is displayed on the
	     right.
	    Return or Escape ends the edit.

				     5
				  MAXDOC  

				  Buffers

	9.  C [Compare] compares buffers A and B, at the start address
	     entered for the length entered. [Both entries in hex.]
	    The result of the compare is displayed at the bottom of the
	     screen.  If there is an error, the comparison may be
	     displayed.
	    Note that this compare is so fast you might think it is fake.
	     To verify it, you can fill both buffers with the same thing,
	     then change one byte at a known address.
	    Compare will find that byte.

	10. F [Fill] has its own set of choices.
	     C [Clear]: fills whole buffer chosen with 00.
	     1: Fills with up to 16 bytes of data pattern you enter.
	     2: Fills with 4-byte LBA [doesn't quite fill each block if
		   blocksize is not even multiple of 4].
		Uses blocksize [set by F1 in main menu].
	     3: Fills with 1 byte data incrementing from 00 to FFh.
	     4: Fills with 2 byte random data.
	     5: Overwrites with 4 byte LBA at beginning of each block.
		Uses blocksize [set by F1 in main menu].

	11. G [Get] buffer file: loads file into buffer.
	     This choice asks you for the file name and length,
	      which buffer, and buffer start address.
	     A path name may be specified with the file name.
	    If the file can't be loaded, the program will tell you.
	     [This usually means the file can't be found, either because
	     it is misspelled or isn't in the current directory or the
	     path specified.]	    
	    This choice loads either the number of bytes requested or
	     the whole file, whichever is less.
	    The bytes loaded are not modified at all; this is a DOS file
	     read [DOS call 3Fh].
	    Therefore this choice is suitable to download and execute
	     binary code.
	    And the buffer can be used as an editable dump if desired.

	12. Q [Quit] leave MAXTEST.

	13. S [Save] buffer file: saves buffer to file.
	     This choice asks you for the file name and length,
	      which buffer, and buffer start address.
	     This function calls a DOS file write [DOS call 40h].
	    As many bytes are saved as you specify to the file name
	     and path you specify.
	    If a file by that name already exists it gets written over.
	    The bytes saved are not changed in any way.

	14. T [Table] lists all files in the current directory.

	15. P [Print] allows printing of buffer A or B starting at
	     a chosen address for a chosen length.  There is also
	     an option to save this section to a printable file.
	     [S does not create a printable file; it is binary.]

	16. L [List] returns to the main menu [SCSI command list].
	    Escape also returns to the main menu.

				     6
				  MAXDOC  

			    Executing commands

		 E [Execute commands] and X are identical.

	1.  This function first asks which commands are to be executed.
	     The command numbers shown at the left of the command
	      [0 - 19] are to be entered.
	     From 1 to 20 numbers may be entered, separated by commas,
	      spaces, or any other non-digits.
	     Escape aborts this user command, leaves the function
	      without executing anything.
	     Return ends the list.
	     If more than 20 numbers are entered, the extras are
	      ignored.

	2.  If linked commands are to be executed, only enter the
	     FIRST command of the linked chain in the command list.
	    The program will follow the rest of the chain, as long
	     as the linked bit is set in the command.

	3.  Next the function asks for options.
	     A brief list of the options appears at the bottom of
	      the screen.
	     Return with no options entered means execute the command
	      string 1 time.
	     Return with options entered ends the options list.
	     Escape means abort the user command.
	     # of passes may be a number from 0 to 65536.
	      0 means run until a key is hit.
	      Any other number executes the command string for that
	       many times.
	     L [Loop] means the same as 0 passes...run until a key hit.

	4.  I [Incrementing] and R [Random] use the parameters entered
	     with the I user command.  See the description of I.
	     [Defaults are length 1 to 80h, LBA 0 to 2FFFFh].
	    But note that if the lowest and highest LBAs are the same,
	     R and I will use the value displayed in the command on
	     the screen, and will not randomize or increment that LBA.
	    The same is true of the length; if the longest length and 
	     shortest length are the same, the length displayed is used.

	5.  R and I as options only work on read, write, seek, and
	     write verify commands.
	    For other commands they are ignored.
	    S [Step] only has meaning with the I option; otherwise it
	     is ignored.
	    The number entered for Step is in hex.  Normally Step is
	     used to advance by the number of blocks being transferred.
	    So if a fixed block transfer of 80h is used, then S 80 will
	     increment the LBA by 80h, so all blocks will be read once. 

				     7
				  MAXDOC  

			    Executing commands

	6.  I [Incrementing] means increment the LBA by the hex number
	     entered immediately after S [Step] or by 1 if step not
	     entered, unless the LBAs or lengths are the same.
	    When the highest LBA is reached, the numbers start over 
	     with the lowest.
	    I also increments the data length from the shortest to the
	     longest length, then starts over.  [Only increments by 1].

	7.  R [Randoming] randomizes the LBA and length each time the
	     command is executed, unless the LBAs or lengths are the same.

	8.  A pass count may be entered with R or I; then the program
	     will loop until the pass count is reached or a key is hit.

	9.  Once the command list and option list have been filled,
	     execution begins.
	    If screen update has been suppressed [F7], a message will
	     appear at the bottom of the screen: Screen update suppressed.
	    Otherwise, the commands to be executed are marked with an
	     arrow at the right side of the screen.

	10. When each command is finished, the program will find it and
	     check the return code in the mailbox.
	    A return code of 01 means good completion, so the program
	     goes to the next command if there is one, or returns to
	     the main menu if all are finished.
	    When each command has been completed, the arrow marking the
	     command is erased.
	    A return code of 04 means error completion.  The program
	     puts the error codes in the appropriate place in the
	     screen display.
	    Then it does whatever has been set up for error handling
	     in the O [error options] user command.
	     [Default error option is stop on any error.]

				     8
				  MAXDOC  

			     Main Menu choices

	1.  B [Bring buffer file] loads file into buffer.
	     This is the same exact function as G in the buffer menu.
	    You are prompted to enter the file name [with path if
	     desired], length in bytes, which buffer, and buffer start
	     address.
	    Either the whole file is loaded or the number of bytes
	     requested, whichever is less.
	    After the file is loaded, the buffer is displayed at the
	     start address requested, and you are in the buffer menu.

	2.  C [Clear entire buffer] fills requested buffer with 00,
	     but does not enter the buffer menu.

	3.  D [Data] saves buffer to file.
	     This is the same exact function as S in the buffer menu.
	    You are prompted to enter the file name [with path if
	     desired], length in bytes, which buffer, and buffer start
	     address.
	    The number of bytes requested are saved.
	    If a file by that name exists, it gets overwritten.
	    You stay in the main menu after the file is saved.

	4.  E [Execute commands] sets up which commands will be
	     executed and which options.
	    See the description under Executing commands.

	5.  G [Get command file] loads a previously defined command
	     file into the SCSI command list on the main screen.
	    This may also be done by naming the file when calling
	     the program.  Example: maxtest cmds.

	6.  H [Help menu] displays the main help menu.
	    Any user command [any of the menu choices] may be executed
	     from the help menu if desired.

	7.  I [Initialize random/incrementing parameters] lets you set
	     the lowest and highest LBA and the shortest and longest
	     transfer length in blocks.
	    These parameters are used only when R or I is selected
	     as an execution option.
	    Defaults are LBA 0 to 2FFFFh, length 1 to 80h.
	    Current values are accepted just by hitting return at the
	     prompt.
	    Otherwise enter the desired number.
	    LBA is a 4 byte number in hex [FFFFFFFF].
	    Length is a 1 byte number in hex [FF].	    
	    The last choice under I is whether to change the random or
	     incrementing parameters when each command is called or
	     for the whole command string.
	    When you execute only 1 command in the command list, this
	     doesn't matter.  If you execute more than one, you will
	     see that no two commands have the same numbers when the
	     choice was "by command".
	    If "by command string" was chosen, all the numbers will be
	     the same for each pass of the command string. 

				     9
				  MAXDOC  

			     Main Menu choices

	8.  L [List] returns to the main screen and menu from the
	     buffer menu, or redraws the main screen from the main menu.

	9.  K [Kill] deletes and re-initializes the current log file,
	     effectively erasing the contents but keeping the file.

	10. M [Modify command] edits the SCSI command list.
	     See the description under Editing commands.

	11. Q [Quit] leaves the program and returns to DOS.

	12. R [Read buffer] enters the buffer menu.
	     See the description of the buffer menu under Buffers.

	13. S [Save command file] saves the current set of commands
	     under whatever name and path you choose.

	14. T [Table] displays the current directory.  If more than
	     one screen is needed to display all files, you will be
	     prompted to hit a key to see the next screen.

	15. U [Display logfile] displays whichever logfile you
	     choose.  Options are Page up, Page down, Home [go to
	     first record in file], End [go to last record in file],
	     # [jump to a record number], Escape [return to main menu].

	16. W [Write buffer] enters the buffer menu in edit mode.
	     See the description of the buffer menu under Buffers.

	17. X [Execute commands] sets up which commands will be
	     executed and which options. [Same as E].
	    See the description under Executing commands.

	18. Y executes the last command string with its options.
	     This does exactly the same as E and X, but without
	     requesting any user input.  It just repeats the last
	     set.

	19. Z [Zap] does a SCSI bus reset and a host adapter reset.
	     If synchronous is jumpered, a synchronous negotiation
	     is initiated.
	    [The host adapter will always respond to a target-initiated
	     synchronous negotiation.]

	20. ? and / display 256 bytes of sense information for the
             requested SCSI command.

				    10
				  MAXDOC  

			     Main Menu choices

	21. & [shift-7] toggles learn mode.  If learn mode is 
	     off, it gets turned on; if on, it gets turned off.
	    When entering learn mode, you are asked for a file
	     name.  The file chosen writes over any previous file 
	     by that name.  The file may be any name and any length
            that fits in the specified directory.  Two bytes are
            saved for each key hit.
	    In learn mode, all keys hit are saved to the learn file,
	     including mistakes and corrections.  So anything you
	     can do in MAXTEST can be done in a learnfile.  Each key 
	     saved is also executed.  The file gets closed when
	     leaving MAXTEST if not before. 
           Currently only the Data Transit can not be accessed by a
            learnfile.
	    Be sure that you include loading any needed commandfile
	     in your learnfile.
	    Selecting '&' again closes the file and exits learn mode.

	22. @ [shift-2] executes a learned file for a loopcount from
            1 to 4 bytes of count [about 4 billion].  Default is 1.
	    A learnfile can also be executed from the command line
	     by entering -L or -L= followed immediately by the 
	     learnfile name.  Example: MAXTEST CMDS -L=MYTEST.LRN
           From the command line the file is executed 1 time.
           YOU ARE RESPONSIBLE for being sure the filename is 
	     truly a learnfile; MAXTEST doesn't know.  Results are
	     unpredictable if it is not.

	23. F1 sets block size.  It is ABSOLUTELY REQUIRED that the
	     block size be correct.  The host adapter has no way of
	     finding out except by this user command.
	    Blocksize is entered in hex, so it can be read from mode
	     sense.
	    Default is 200h [512 decimal] bytes.
	     If this is changed, use F1!

	24. F2 sets a timeout in seconds for each command string
	     execution.
	    It times the execution of ONE command string; it is 
	     reinitialized each time the command string is started
	     in a loop.
	    Default is 3600 seconds or 1 hour; maximum is 65535 seconds.
	     This default is long to allow for a format with certify.
	    You don't really need this to stop command execution
	     interactively, because hitting a key will stop it.
	    But it is useful if you are running in a loop.

	25. F3 resets the host adapter and the SCSI bus.
	     If synchronous is jumpered, a synchronous negotiation
	     is initiated.

	26. F4 displays the installed SCSI devices.
	     This function takes a few seconds to execute.

				    11
				  MAXDOC  

			     Main Menu choices

	27. F5 displays the synchronous setup.
	    Warning: if F8 is executed after synchronous transfers
	     have been set up, this function still reports that
	     synchronous transfers are being used.
	    The default synchronous speed is 5 megabytes [200 ns],
             and the default offset is 7.
	    MAXTEST cannot change these.
	    The target can negotiate down from here, but not up.

	28. F6 allows setting the maximum transfer speed.
	    This is the transfer speed between the host adapter and
	     the computer, not the SCSI bus transfer speed.
	    But this is the maximum speed that the SCSI bus can truly
	     run, no matter what is negotiated.
	    Note that potentially asynchronous can run pretty fast also.
	     There is no arbitrary host adapter defined limit.

	29. F7 allows suppressing screen update, to get the fastest speeds.
	    This does not affect the actual command execution timing, but
	     shortens the program overhead between command string
	     executions.

	30. F8 does a SCSI bus reset, but the host adapter does not
	     initiate a synchronous negotiation.
	    This is a way to force asynchronous transfers.
	    Note that F5 still displays that synchronous is in effect.

	31. F10 sets the target ID for all commands on the screen to
	     whichever ID is selected.  If the selected ID is the same
	     as the host ID, you will be prompted to pick another ID.

	32. Control A calls the Data Transit Bus Analyzer.
	    The analyzer must be connected to a serial port on the
	     computer...either COM1 or COM2.  The program will
	     self-configure to either port.
	    The baud rate in the program is 19.2K.  Be sure the baud
	     rate switches on the Data Transit are set to 19.2K.
	    To use the analyzer, set it up first, start it, then 
	     execute the command[s] from MAXTEST.
	    When you want to look at the output, select Control A.
	    If nothing appears on the screen, hit M for menu.  If
	     the Data Transit doesn't respond in 2 seconds, a 
	     message will appear on the screen telling you so.
	    Otherwise the screen and keyboard will behave as described
	     in the Data Transit manual.

	    The Data Transit owns the screen and the keyboard in
	     this mode, with two keyboard exceptions.
	    A choice of 'T' will print the screen. [In most cases,
	     so will the computer's PrintScreen.]
	    Escape will return to the MAXTEST main menu.

				    12
				  MAXDOC  

			     Main Menu choices

	33. Control H displays the meanings of host adapter error codes.
	    These are returned in the column under STATUS HO.

	34. Control M displays all mailboxes.
	    Mailboxes are also displayed if you hit return to stop an
	     execution loop or a hang.

	35. Control P will print the current screen.  Use the system
	     Printscreen if it works, because DOS fights for Control P.

       36. Control R lets you turn automatic request sense off or on.
            Normally this should always be ON.

	37. Control S allows you to seed the random number generator.
	    This accepts a 4 byte hex number.  The lowest byte must not
	     be all 0.
	    The same sequence will be generated from the same seed.
	    Note that the fill random in the buffer uses the same
	     random number generator, so will be affected by this function.

	38. Control T times the FIRST command in the command string.
	    Timing is in 1/3 of a millisecond increments, so this is a
	     rough timer....not the same as a logic analyzer.
	    It is useful for comparing the effect changes have made on
	     performance.
	    The timer is also slightly affected by computer clock speed.
	     At 8 mhz 1 less pass was averaged than at 20 mhz on my setup.
	    Timing starts when you select S under Control T, and continues
	     until you end it or leave the program.
	    So be sure to initialize it when you want to time something.
	    65535 passes may be timed, then it will overflow.
	    Four bytes of times are added up to average.
	     This could also overflow, but that's a pretty big number.
	    Timing results can be displayed [without stopping the timing]
	     by choosing D under Control T.

	39. Control U [user choices] lets you select beep tones of low,
	     medium, or high for beep on error.  It also allows some
	     choices of color.  This choice is not offered on monochrome.

	40. Control W turns buffer wrap on and off.
	     See the description of buffer wrap under Buffers.

				    13
