home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 4 Drivers / 04-Drivers.zip / scsiopt2.zip / scsiopt.doc < prev    next >
Text File  |  1998-03-04  |  11KB  |  355 lines
  1. -*- Mode: indented-text -*-
  2. --- $Id: scsiopt.doc,v 1.4 1998/03/04 02:24:32 vitus Exp $
  3.  
  4.     SCSI Optimizer - Driver Dokumentation
  5.  
  6.  
  7. DESCRIPTION
  8.  
  9.     SCSIOpt is a simple OS/2 filter driver to modify some performance
  10.     related mode pages of your SCSI devices.
  11.  
  12.     Source code  is included to serve  as  a sample how  to  write a
  13.     16bit driver.
  14.  
  15.  
  16. LEGAL STUFF (we need this, don't we?)
  17.  
  18.     The author  disclaims all warranties  as to this software, whether
  19.     express  or  implied,  including  without limitation  any  implied
  20.     warranties of  merchantability, fitness for  a particular purpose,
  21.     functionality,  data  integrity  or   protection,   in so  far  as
  22.     permitted by applicable legislation.
  23.  
  24.     All trademarks are property of their respective owners and appear
  25.     for identification purposes only.
  26.  
  27.     There is a copyright  on some  source code  files in  this archive
  28.     (cmd* files) but as they are freely distributed via IBM's webpages
  29.     I don't think this is a problem.  All other sources are put to the
  30.     public domain in the hope that they may be usefull.
  31.  
  32.  
  33. CAUTION
  34.  
  35.     Modifying mode  pages on SCSI devices is  a very low-level action.
  36.     Although I have  never encountered a  totally useless device  when
  37.     experimenting with SCSIOpt.flt you may end up reading strange data
  38.     (which in turn may lock up your  OS/2).  For this reason I decided
  39.     that this driver  will never save a mode  page permanently.   Just
  40.     power cycle your machine, remove  SCSIOpt.flt from your config.sys
  41.     (booting from  floppy if neccessary) and  you are back to what you
  42.     had before trying SCSIOpt.flt.
  43.  
  44.  
  45. INSTALLATION
  46.  
  47.     It is recommended you  have an OS/2 boot disk  ready, just in case
  48.     the system locks up during the boot process and you want to remove
  49.     the driver.  On Warp you may use ALT-F1, C for the same purpose to
  50.     boot to a command line with your orginal Config.Sys.
  51.  
  52.     Execute DDINSTAL from a  OS/2 command  prompt or double-click  the
  53.     Device Driver Install object  (located in the System Setup folder)
  54.     if your system is Warp.  Change the source directory if neccessary
  55.     and a  selection list will  open asking you   to install the 'SCSI
  56.     Optimizer'.  Mark that line and click on OK.
  57.  
  58.     Installation by hand is easy:
  59.  
  60.     Copy  SCSIOpt.flt to c:\ or  c:\os2\boot, assuming c: is your
  61.     boot drive.
  62.  
  63.     Edit  your  c:\Config.Sys file (i.e.  using  the  OS/2 "System
  64.     Editor"):
  65.  
  66.     Add the following line to your Config.Sys:
  67.     BASEDEV=SCSIOpt.flt /V        (no subdirectory name!)
  68.  
  69.     The  position   of  'BASEDEV=SCSIOpt.flt' in  Config.Sys  doesn't
  70.     matter.  If, however, you encounter  problems try top of file  (if
  71.     this  solves  your problems please report  with  a listing of your
  72.     Config.Sys).
  73.  
  74.     After installation this driver will do nothing but search for SCSI
  75.     devices and display  their  coordinates.  This  will allow you  to
  76.     select the devices you might be able to modify.
  77.  
  78.     No  modifications  are actually done.   See  below  how  to modify
  79.     pages.
  80.  
  81.  
  82. OPTIONS
  83.  
  84.     Two general options, i.e. option which have to appear before any
  85.     '/A:n' option:
  86.  
  87.     /V
  88.     Verbose, display some usefull and unusefull information (this
  89.     switch is enabled in automatic installations).
  90.     Without this switch the driver will be quiet except for fatal
  91.     errors.
  92.  
  93.     /DEBUG
  94.     Debugging display, a lot of.
  95.  
  96.     One  word  about screen output:    BASEDEV drivers cannot  display
  97.     anything   on the console  immediately,  they queue messages to be
  98.     displayed later by  the  system initialization.  Due to  this fact
  99.     you might not   see any  messages at  all  (if system  hangs/traps
  100.     before they are yanked to console).
  101.  
  102.     Best chances to see anything is to copy  this driver to the second
  103.     of your  "utility disks" (or installation  disks  if you don't run
  104.     Warp), change  the Config.Sys there (BASEDEV=SCSIOpt.flt /DEBUG
  105.     and boot from them.  Now you don't rely on any SCSI device.
  106.  
  107.     If you get  a  SYS2068 at  boot time,  all messages  generated  by
  108.     BASEDEV    drivers exceed a  kernel limit   and nothing  at all is
  109.     displayed.  Ignore  that  error and   use SCSIOpt.exe  to  display
  110.     SCSIOpt.flt messages or change options to display less.
  111.  
  112.  
  113.     Adapter selection option:
  114.  
  115.     /A:n
  116.     'n' is an index, it depends on the ADD order in your
  117.     Config.Sys and numbers all adapter (including floppy
  118.     controllers, etc.).
  119.  
  120.  
  121.     Unit control options (used after /A:n):
  122.  
  123.     /E:(u1,page1,mask1),(u1,page2,mask2),...
  124.  
  125.     /!E:(u1,page1,mask1),(u2,page2,mask2),...
  126.  
  127.     'u' is  an unit index which  the  ADD determines.   BTW: these
  128.     values  are  displayed by   SCSIOpt.flt during  boot if /V  or
  129.     /DEBUG option is provided.
  130.  
  131.     These options allow you to specify which pages to modify.  Use
  132.     '/E:' to enable   features and '/!E:' to   disable them.   Any
  133.     combination  is valid, the last  option of conflicting options
  134.     will survive.
  135.  
  136.  
  137. MODE PAGE OPTIONS
  138.  
  139.     As the general layout of a mode page option is (<unit index>,<page
  140.     number>,<mask>) you have three values to supply:
  141.  
  142.     <unit index>    this value depends on the ADD which controls
  143.             a unit.  Enable SCSIOpt's option '/V' and you
  144.             will see messages telling what indexes were
  145.             found.
  146.  
  147.     <page number>    tells SCSIOpt which page to change
  148.  
  149.     <mask>        tells SCSIOpt which features of a mode page to
  150.             enable/disable.  This is a bit-coded value
  151.             (but decimal...).
  152.  
  153.     page    bit(2^x) description (enable/disable ...)
  154.  
  155.     2    0    ... disconnect because of empty (read) or full
  156.             (write) buffers
  157.     2    1    ... inactive bus timeout
  158.     2    2    ... disconnect timeout
  159.     2    3    ... connect timeout
  160.  
  161.     8    0    ... write cache
  162.     8    1    ... read cache
  163.     8    2    ... prefetch
  164.     8    3    ... higher importance of prefected data than
  165.             regular data
  166.  
  167.     10    0    ... tagged queuing
  168.     10    1    ... unrestricted command reordering
  169.  
  170.     13    <all>    ... seconds until CD-ROM stops spinning (up to
  171.                 1920 supported (= 32 minutes)) [this is *not*
  172.                 bit-coded!]
  173.  
  174.  
  175.     Hint: if you set 'page'  to a supported value  and 'mask' to  zero
  176.     SCSIOpt   will read  that page and    test whether it has  SCSI-II
  177.     layout.  If you add '/V' to your command line  it will display the
  178.     current settings, too!
  179.  
  180.  
  181. SUPPORT PROGRAMS
  182.  
  183.     SCSIOpt.flt   contains    a simple   IOCtl   interface   to  allow
  184.     applications to retrieve  messages displayed at  boot time.  It is
  185.     described in dskpfpub.h and used by SCSIOpt.exe.
  186.  
  187.     Just execute SCSIOpt without parameters  and it will display those
  188.     messages.  Very simple.
  189.  
  190.  
  191. TESTED EQUIPMENT
  192.  
  193.     I added  a list of option which  were tested with my devices here.
  194.     Keep in mind that in SCSI many things are free to support, so even
  195.     with a newer device you might have less options to change.
  196.  
  197.     If  you happen to  know a vendor unique mode  page  that you think
  198.     should  be  modified: please mail vendor  string,  device and mode
  199.     page description.
  200.  
  201.  
  202.     Western Digital - Piranha SP4200
  203.  
  204.     Disconnect-reconnect page(2)
  205.  
  206.         buffer full/empty    not supported
  207.         bus inactive    not supported
  208.  
  209.     Cache Page(8)
  210.  
  211.         Read Cache Disable    supported
  212.         Write Cache Enable    not supported
  213.         pre-fetch        not supported
  214.         priority        not supported
  215.  
  216.     Control Page(10)    - cannot be read
  217.  
  218.  
  219.     IBM DORS-32160
  220.  
  221.     Disconnect-reconnect page(2)
  222.  
  223.         buffer full/empty        supported
  224.         bus inactive timeout    not supported
  225.         connection timeout        not supported
  226.         disconnection timeout    not supported
  227.  
  228.     Cache Page(8)
  229.  
  230.         Read Cache Disable    supported
  231.         Write Cache Enable    supported
  232.         pre-fetch        supported
  233.         priority        not supported
  234.  
  235.     Control Page(10)
  236.  
  237.         Algorithm        unrestricted and restricted supported
  238.         tagged queuing    not tested
  239.  
  240.  
  241.     Sony CDU-615S
  242.  
  243.     Disconnect-reconnect page(2)
  244.  
  245.         buffer full        not supported
  246.         bus inactive    not supported (device ignores new values)
  247.  
  248.     Cache Page(8)        - cannot be read
  249.  
  250.     Control Page(10)    - cannot be read
  251.  
  252.     CDROM Page(13)        - supported
  253.  
  254.     Tandberg TDC-3660
  255.  
  256.     Disconnect-reconnect page(2)    - cannot be read
  257.  
  258.  
  259.     Seagate WREN Runner 7 (Imprimis)
  260.  
  261.     Layout of mode pages isn't SCSI-II compatible.
  262.  
  263.  
  264.  
  265. TODO LIST
  266.  
  267.     - Ideas from YOU?
  268.  
  269.     - remove SCSIOpt.flt   from memory  to save  some   KB of  memory.
  270.       Perhaps  switched on or   off  with a parameter  (/V  -  keep in
  271.       memory?).
  272.  
  273.     - Keep SCSIOpt.flt  in  memory and write a  simple  .EXE to change
  274.       values at any  time.  But this is the   same I already  did with
  275.       ASPI Router for OS/2  and scache.exe (see aspi01.zip or higher).
  276.       Pro:  it would  demonstrate  a complete  filter; Con: it's  more
  277.       dangerous to change at runtime as at  boot time (a SCSI bus hang
  278.       or reset affects all devices on that bus).
  279.  
  280.     - easier user  interface to select which pages  and how to modify.
  281.       I'm most certainly not satisfied with the current solution.
  282.  
  283.     - Use Daniela Engert's description to make  this driver full 32bit
  284.       without  mwdd32.zip.   Nice   exercise and would   support  more
  285.       compilers.
  286.  
  287.  
  288. COMPILING
  289.  
  290.     What do you need?
  291.  
  292.     - IBM's DDK for OS/2:
  293.  
  294.     available     from   http://service.boulder.ibm.com/ddk/ after
  295.     registration at no charge.
  296.  
  297.     - a 16bit C compiler
  298.  
  299.     supported out of the box  are Micro Soft C  5.1 - 7.0 (request
  300.     C7OS2.ZIP to get those OS/2 files  Micro Soft removed from the
  301.     7.0 release) and WatCom C 10.0 and higher.
  302.  
  303.     IMHO Visual C 1.x should work, too; but you would have to use
  304.     a MDOS session.
  305.  
  306.     You should be able to use any other 16bit compiler for OS/2
  307.     or DOS, but would have to make the modifications yourself.
  308.  
  309.     - a 16bit assembler
  310.  
  311.     the DDK  ships with  MASM 5.1 and  ALP.  Makefiles  are mostly
  312.     written for MASM, but TASM or (brrr) WASM should be possible.
  313.  
  314.     It's  only a  single file  if you  don't  plan to  rebuild the
  315.     support libraries supplied by the DDK.
  316.  
  317.     - DMake
  318.  
  319.     DMake    3.8  and  4.0   are   available  as  dmake38.zip  and
  320.     dmake40o.zip.  Porting to a GNU Make compatible tool shouldn't
  321.     be too much work.
  322.  
  323.     Actually compiling
  324.  
  325.     - setup your compiler (PATH and INCLUDE files)
  326.     - extract long arithmetik support routines (see Makefile)
  327.     - edit Makefile (path to DDK)
  328.     - type 'DMake debug all'
  329.  
  330.     Debugging
  331.  
  332.     - Debugging device  drivers is documented  in  the DDK.   It's not
  333.       complicated but you need some time to get used to it, especially
  334.       if you  plan  to  use a  simple   terminal (as I  like   to do).
  335.       Expirience with DEBUG or SYMDEB is helpfull.
  336.  
  337.  
  338. AUTHOR
  339.  
  340.     Vitus Jensen
  341.  
  342.     Address: Tischlerstr. 8, D-30916 Isernhagen, Germany
  343.     Fidonet: 2:2474/424, OS2Net, TeamOS/2 Net
  344.     Usenet: Vitus_Jensen@teaparty.fido.de
  345.     BBS: +49-5136-893003 (X.75, V32bis)
  346.     FAX: +49-5136-893003
  347.  
  348.     Music: J.S.Bach Orchestersuiten, J.S.Bach Goldberg-Variationen
  349.  
  350.     Written for Version: 0.71
  351.     Date: 03.03.1998
  352.     Other products: dsksl*.zip, dtest*.zip, aspio*.zip
  353.  
  354. === The End ===
  355.