home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 27 / amigaformatcd27.iso / -websites- / phoenix / html / files-lha / makecd31.lha / MakeCD_3.1 / Goodies / NSDPatch / README.FIRST < prev   
Encoding:
Text File  |  1997-12-16  |  14.9 KB  |  396 lines
  1.  
  2.     $Id: README.FIRST 1.20 1997/12/15 18:55:56 heinz Exp $
  3.  
  4. NSDPatch
  5. ========
  6.  
  7. What is NSDPatch?
  8. -----------------
  9.  
  10. NSDPatch will hook into the OS (V37+, 2.04+) and patch almost
  11. arbitrary types of Exec devices to make them look like NSD compliant
  12. devices. With a configuration file, you can set up NSD like
  13. behaviour even for most devices that were not known to the authors
  14. of NSDPatch. NSDPatch does not affect DOS devices like PAR: in
  15. any way. NSDPatch only handles Exec devices.
  16.  
  17. NSDPatch also includes some support for trackdisk like devices to
  18. emulate the NSD 64 bit access commands on top of old devices. With
  19. NSDPatch and the AI V43 FFS, you can use partitions >4GB on disks
  20. >4GB.
  21.  
  22. NSDPatch also includes RDB mount functionality to support special
  23. configurations.
  24.  
  25. NSDPatch also fixes some bugs with certain devices like the V40
  26. mfm.device or incompatibilities of, e.g., a JAZ drive and V40
  27. scsi.device.
  28.  
  29. NSDPatch will allow you to turn on correct command rejection via
  30. IOERR_NOCMD for devices that would crash otherwise.
  31.  
  32. NSDPatch will optionally try to do some magic for broken SANA2
  33. devices, too.
  34.  
  35. NSDPatch may also be useful for developers of NSD using SW to
  36. simulate different and possibly incomplete or buggy NSD
  37. environments for testing.
  38.  
  39. NSDPatch makes it possible to install device/unit mappings to
  40. virtually rename device units to support broken software that
  41. test only the device name for assumed functionality.
  42.  
  43. NSDPatch is not intended to replace an NSD upgrade for old devices
  44. forever. It is also not intended to provide for every single NSD
  45. bell and whistle in the specs. It is intended to ease the migration
  46. path and to give some basic NSD capabilities and convenient fixes
  47. to those who otherwise couldn't have it at all.
  48.  
  49.  
  50. What is NSD?
  51. ------------
  52.  
  53. NSD is referring to the New Style Device standard as documented on
  54. the Amiga Technologies Amiga Developer CD in the
  55.  
  56.     Amiga_Dev_CD_v1.1:DevInfo/DeviceDevelopment
  57.  
  58. directory. It is intended to provide for clean device usage in the
  59. future.
  60.  
  61. Updates to this standard are available on ftp.amiga.de or
  62. www.amiga.de and it is probably a good idea to check for them once
  63. in a while.
  64.  
  65. If you want more information about NSD, you can also contact the
  66. author of this document at the address mentioned below.
  67.  
  68.  
  69. WARRANTY AND LEGALES
  70. --------------------
  71.  
  72. WARRANTY: None whatsoever. Standard disclaimer applies.
  73.  
  74. LEGALESE: FREELY REDISTRIBUTABLE, NOT PD! CHANGES NOT ALLOWED!
  75.  
  76.  
  77. Installation
  78. ------------
  79.  
  80. ****************
  81. *** READ IT! ***
  82. ****************
  83.  
  84. There is an Installer-Script "Install" included, that does a quick
  85. installation and setup of NSDPatch, including its configuration.
  86. If you go this way, you may still want to read below about what
  87. happens. If you don't want the automatic installation, you can read
  88. below about the details of a custom installation.
  89.  
  90. First, take a look at the demonstration configuration file
  91. NSDPatch.cfg. It describes in detail all the available
  92. configuration options and contains all the entries for a basic OS
  93. 3.1 based system including entries for devices known to be broken.
  94. When you have looked it over and want to boldly go where quite a
  95. few now have gone before, proceed like this:
  96.  
  97.   A. BASIC INSTALLATION
  98.  
  99.     1. Make a copy of the file NSDPatch.cfg, and and place it
  100.        preferrably into SYS:DEVS, with SYS: referring to your boot
  101.        volume.
  102.  
  103.     2. Copy NSDPatch into SYS:C.
  104.  
  105.     3. Check the configuration file in SYS:DEVS for any devices
  106.        that you don't want to have patched and comment out these
  107.        lines. Add entries for any special devices. Please report
  108.        configuration lines for 3rd party devices to the author.
  109.        Keep another copy of your changes in case of future
  110.        automatic updates. Use NSDQuery to check if a device already
  111.        supports NSD.
  112.  
  113.     4. Place a line like this into your SYS:S/Startup-Sequence
  114.        immediately after SetPatch is called:
  115.  
  116.         NSDPatch
  117.  
  118.        It is very important that this line is added immediately
  119.        after SetPatch. That is why NSDPatch must be placed into
  120.        SYS:S/Startup-Sequence and not in User-Startup.
  121.  
  122.        Alternatively, you can run the included Installer-Script
  123.        "Install", which does a quick installation of NSDPatch.
  124.  
  125.        SPECIAL NOTE: If you map trackdisk.device units, you must
  126.        start any "noclick" hack _after_ SetPatch but _before_
  127.        NSDPatch.
  128.  
  129.     5. Reboot and watch the messages that are output by NSDPatch.
  130.        These messages tell you what NSDPatch does. If you can't
  131.        agree with them in some way, go back to 3.
  132.  
  133.     6. Try NSDQuery on patched devices to check if everything was
  134.        successful. If you encounter problems that can't be fixed
  135.        by going back to 3., check B and C below.
  136.        Please report all problems to the author with the device
  137.        names and versions that cause the problems!
  138.  
  139.     7. Assuming there were no problems, add the "QUIET" option to
  140.        the NSDPatch line in your startup.
  141.  
  142.     8. That's it. This is the end of a successful installation.
  143.  
  144.  
  145.   B. SPECIAL INSTALLATIONS
  146.  
  147.     1. You may have 3rd party devices which don't support
  148.        IOERR_NOCMD correctly. This means that the driver will not
  149.        reject unknown commands with IOERR_NOCMD, but either crash
  150.        or do very strange things instead. In that case, use the
  151.        IOERRNOCMD option for the respective patch configuration
  152.        line. If you want to boot from such a device, read the
  153.        description of the RDBUNIT option carefully. If you
  154.        encounter such a device, please report it to the author.
  155.  
  156.     2. You may have a trackdisk like device supporting the 3rd
  157.        party TD64 command set. In that case, use the TD64 option
  158.        for the respective patch configuration. By using the
  159.        TD64 option, the official NSD 64 bit commands will be
  160.        rerouted to the already existing TD64 functionality instead
  161.        of being emulated via HD_SCSICMD. Current Guru-ROM's and
  162.        Phase 5 SCSI devices may support TD64. No exact versions can
  163.        be named at this time.
  164.  
  165.     3. NSDPatch can be invoked multiple times to install more
  166.        patches. Installed patches cannot be changed without a
  167.        reboot.
  168.  
  169.     4. You can invoke NSDPatch with a config file that doesn't
  170.        actually patch anything but only uses the ACTIVATE and
  171.        RDBUNIT features of NSDPatch. This is considered a positive
  172.        side effect of the NSDPatch design.
  173.  
  174.     5. You may have a SANA2 device that can't handle a NULL
  175.        ios2_BufferManagement pointer on startup. If you have one of
  176.        those, you'll get enforcer hits with most likely an access
  177.        to address 0 first on a check with NSDQuery. In that case,
  178.        specify the SANA2MAGIC option in the configuration.
  179.  
  180.  
  181.   C. TROUBLE SHOOTING
  182.  
  183.     1. In the unlikely case that NSDPatch crashes your machine on
  184.        the first invocation, you may want to
  185.  
  186.         - try NSDPatch with an empty configuration file to verify
  187.           basic installation compatibility.
  188.  
  189.         - reduce the configuration file to a single line, e.g. for
  190.           parallel.device to make testing easier.
  191.  
  192.         - check your system for any virus
  193.  
  194.     2. If you are not sure if a patch was successful, use the
  195.        NSDQuery tool to check on that device.
  196.  
  197.     3. If multiple calls to NSDQuery while a device is in memory
  198.        reveal that the reported io_Device value changes for every
  199.        invocation, NSDPatch will not be able to patch this device
  200.        for any openers that opened the device before NSDPatch was
  201.        installed. This is not a bug in NSDPatch.
  202.  
  203.     4. If NSDQuery behaves strangely on any device, patched or not,
  204.        please report the exact circumstances, including all
  205.        configuration and version information for your Amiga.
  206.  
  207.     5. The NSDPatch 64 bit disk emulation capabilities or the
  208.        FIXSCSIUPDATE option may not work as expected on an IDE
  209.        scsi.device that has been patched by atapi.device. This is
  210.        not a bug in NSDPatch.
  211.  
  212.   D. ADDING NEW PATCH LINES
  213.  
  214.     1. The safe solution is emailing a copy of the device in
  215.        question to the author. He will generate a suitable patch
  216.        line to be placed into NSDPatch.cfg. The quick and dirty
  217.        solution is outlined below.
  218.  
  219.     2. First make sure that everything important is saved because
  220.        the tests for what you need may crash the system. If
  221.        possible, run Enforcer.
  222.  
  223.     3. Try NSDQuery on the device. If your Amiga crashes or severly
  224.        misbehaves, you will need the IOERRNOCMD option! If you get
  225.        a report that the device is NSD, you don't need to patch it.
  226.  
  227.     4. Check NSDPatch.cfg for an existing similar line and make
  228.        a copy, changing the name appropriately. If you have, e.g.,
  229.        magicscsi.device, you may want to use the line
  230.        for scsi.device as first approximation and put the name
  231.        magicscsi.device into the copied line. For, e.g.,
  232.        mynewaudio.device, you would take the line for audio.device
  233.        as example.
  234.  
  235.     5. Put the new line with the device's name into NSDPatch.cfg.
  236.        If needed according to 3., add the IOERRNOCMD option if it
  237.        isn't already there.
  238.  
  239.     6. Start NSDPatch and try NSDQuery again. Now, the device
  240.        should respond as NSD device, based on the new config line.
  241.  
  242.     7. Never change too many patch options at once. After changing
  243.        a patch option, you must reboot for it to take effect.
  244.        Read the descriptions in NSDPatch.cfg before using options.
  245.  
  246.     8. In case of any more problems, contact the author.
  247.  
  248.     9. If the patch line works well and solves your problems,
  249.        please forward it to the  author.
  250.  
  251. Contact
  252. -------
  253.  
  254. If you have any comments on NSDPatch, please send them to:
  255.  
  256.     Heinz Wrobel
  257.     Karlstr.16
  258.     82131 Gauting
  259.     Germany
  260.     <heinz@hwg.muc.de>
  261.  
  262.  
  263. Implementation
  264. --------------
  265.  
  266. This may not be very interesting to most readers as it hints at
  267. some technical details. NSDPatch hooks itself into the exec.library
  268. OpenDevice() function. It will patch any opened device that should
  269. be patched and "preprocess" requests sent to it this way. The user
  270. software sees an NSD device then and the device itself will not
  271. have to be reworked in strange device specific ways. Devices
  272. patched like this can still be expunged and reloaded freely. The
  273. permanent NSDPatch footprint in memory is about 4KB plus memory for
  274. configuration data for each device to be patched. NSDPatch does not
  275. need to be started in the background and it does not use any ugly
  276. SegList splitting hacks or similar stunts. NSDPatch should also be
  277. compatible to all debugging tools.
  278.  
  279.  
  280. History
  281. -------
  282. 43.17
  283.     - As it turns out, there are devices that fail to open, do not
  284.       set io_Device and return with no error. NSDPatch "fixes" this
  285.       now to avoid crashes and returns IOERR_OPENFAIL in that case.
  286.  
  287. 43.16
  288.     - Even more patch lines added. Now a new option INTBEGINIO is
  289.       available to make NSDPatch really safe for devices where
  290.       BeginIO() may be called from within interrupt code. This
  291.       affects the patch lines for audio.device and timer.device.
  292.       The RDB late mount functionality will no longer complain
  293.       about already existing DOS mounts if MOUNTANY has been
  294.       specified. This makes using patterns easier.
  295.  
  296. 43.15
  297.     - The version/revision match code ignored general patch
  298.       requests. This made it impossible to patch, e.g., an ISNSD
  299.       device with FIXSCSIUPDATE.
  300.  
  301. 43.14
  302.     - Cleanup for FIXSCSIUPDATE option. Will ignore an error on
  303.       internal handling now just like scsi.device. This keeps
  304.       FORMAT happy.
  305.  
  306. 43.13
  307.     - Cleaned up some of the 64 bit emulation code. A few SCSI
  308.       CDB's are set up better now. Added FIXSCSIUPDATE option. It
  309.       will turn CMD_UPDATE for scsi.device into something that does
  310.       no longer conflict with JAZ drive behaviour even though it
  311.       should still work as expected for other devices. NSDPatch
  312.       will use significantly less stack in its BeginIO patch for
  313.       patched devices in the general case now.
  314.  
  315. 43.12
  316.     - NSDPatch no longer pops up requesters when activating DOS
  317.       devices. Whenever you specify QUIET as option, NSDPatch will
  318.       no longer complain about already mounted entries when using
  319.       the RDB functionality. More updates to the config file.
  320.       SINLEPATCHONLY is now the default option as it tends to be
  321.       a lot more compatible to many debug tools commonly used with
  322.       AmigaOS. To get the the old behaviour back where the device
  323.       specific patch is reinstalled for each and every OpenDevice,
  324.       you can use the new TRYMULTIPATCH option. Note that with
  325.       other tools patching into the same vectors you may cause
  326.       infinite loops when using this option!
  327.  
  328. 43.11
  329.     - Added MOUNTANY option for RDB support. This facilitates RDB
  330.       mount magic by allowing access to any partition, not just
  331.       partitions not marked as automount. It is meant for the
  332.       advanced user. Added PATCHCONFIGLINE command line option. You
  333.       can use NSDPatch with a single simple config line. It will
  334.       not read in a config file then unless you also specify one.
  335.       The default DEVS:NSDPatch.cfg will now only be read if no
  336.       command line options have been used. Updated the
  337.       configuration file a little.
  338.  
  339. 43.10
  340.     - Added SINGLEPATCHONLY option for device patch lines. With this
  341.       option, a device will only patched for its initial open call.
  342.       This fixes interaction with CMD, which will hang in an endless
  343.       loop without SINGLEPATCHONLY. This again shows how dangerous
  344.       the use of the exec.library SetFunction() call is.
  345.  
  346. 43.9
  347.     - Should work with >=V37 now.
  348.     - Supports device mapping now. Implementation of this feature
  349.       has been funded by ATL, Inc.
  350.  
  351. 43.8
  352.     - Reduced stack usage during OpenDevice() patch by about 32
  353.       bytes. The patch needs about 68 bytes now during OpenDevice().
  354.     - The SANA2MAGIC did not work very well. There was a problem in
  355.       handling paths. So it often did not even get activated.
  356.  
  357. 43.7
  358.     - There was a bug in the Version/Revision recognition.
  359.       NSDPatch patched too much at times. This should not have
  360.       hurt, though.
  361.     - Reduced processing time in OpenDevice() a little.
  362.     - Mixing different versions of NSDPatch should not cause any
  363.       harm now.
  364.     - Added new PatchInfo option that tells you about NSDPatch
  365.       activities. Note: This option is more of a debugging hack!
  366.     - More patch lines.
  367.  
  368. 43.6
  369.     - Now supports LVO's that can't normally be SetFunction()'ed.
  370.     - Now supports version specific patches correctly. The override
  371.       general patches.
  372.     - Now supports special SANA2MAGIC for callback handling of old
  373.       devices.
  374.     - Now checks the default patch file DEVS:NSDPatch.cfg
  375.       automatically, if none has been specified.
  376.     - The config file is no longer named v40.nsdpatchcfg. It now
  377.       already has the default name and also has a C= version
  378.       string.
  379.  
  380. Acknowledgements
  381. ----------------
  382.  
  383. Some were very directly involved in thinking up and testing
  384. NSDPatch. Here is a list in no particular order:
  385.  
  386.     Olaf Barthel
  387.     Bernhard Möllemann
  388.     Michael van Elst
  389.     Angela Schmidt
  390.     Klaus Burkert
  391.     Joanne Dow
  392.  
  393. Thank you.
  394.  
  395. Heinz Wrobel
  396.