
    $Id: README.FIRST 1.9 1997/04/18 14:01:45 heinz Exp $

NSDPatch
========

What is NSDPatch?
-----------------

NSDPatch will hook into the OS (V37+, 2.04+) and patch almost
arbitrary types of devices to make them look like NSD compliant
devices. With a configuration file, you can set up NSD like
behaviour even for most devices that were not known to the authors
of NSDPatch.

NSDPatch also includes some support for trackdisk like devices to
emulate the NSD 64 bit access commands on top of old devices. With
NSDPatch and the AT V43 FFS, you should be able to use partitions
on disks >4GB.

NSDPatch also fixes some bugs with certain devices like the V40
mfm.device.

NSDPatch will allow you to turn on correct command rejection via
IOERR_NOCMD for devices that would crash otherwise.

NSDPatch will optionally try to do some magic for broken SANA2
devices, too.

NSDPatch may also be useful for developers of NSD using SW to
simulate different and possibly incomplete NSD environments for
testing.

NSDPatch makes it possible to install device/unit mappings to
virtually rename device units to support broken software that
test only the device name for assumed functionality.

NSDPatch is not intended to replace an NSD upgrade for old devices
forever. It is also not intended to provide for every single NSD
bell and whistle in the specs. It is intended to ease the migration
path and to give some basic NSD capabilities to those who otherwise
couldn't have it at all.


What is NSD?
------------

NSD is referring to the New Style Device standard as documented on
the Amiga Technologies Amiga Developer CD in the

    Amiga_Dev_CD_v1.1:DevInfo/DeviceDevelopment

directory. It is intended to provide for clean device usage in the
future.

Updates to this standard are available on ftp.amiga.de and it is
probably a good idea to check for them once in a while.

If you want more information about NSD, you can also contact the
author of this document at the address mentioned below.


WARRANTY AND LEGALES
--------------------

WARRANTY: None whatsoever. Standard disclaimer applies.

LEGALESE: FREELY REDISTRIBUTABLE, NOT PD! CHANGES NOT ALLOWED!


Installation
------------

There is an Installer-Script "Install" included, that does a quick
installation and setup of NSDPatch, including its configuration. If
you don't want that automatic installation, you can read below
about the details of a custom installation.

First, take a look at the demonstration configuration file
NSDPatch.cfg. It describes in detail all the available
configuration options and contains all the entries for a basic OS
3.1 based system. When you have looked it over and want to boldly
go where (almost) no one has gone before, proceed like this:

  A. BASIC INSTALLATION

    1. Make a copy of the file, and and place it preferrably into
       SYS:DEVS, with SYS: referring to your boot volume.

    2. Copy NSDPatch into SYS:C.

    3. Check the configuration file in SYS:DEVS for any devices
       that you don't want to have patched and comment out these
       lines. Add entries for any special devices. Please report
       configuration lines for 3rd party devices to the author.
       Keep another copy of your changes in case of future
       automatic updates. Use NSDQuery to check if a device already
       supports NSD.

    4. Place a line like this into your SYS:S/Startup-Sequence
       immediately after SetPatch is called:

        NSDPatch PCF DEVS:NSDPatch.cfg

       It is very important that this line is added immediately
       after SetPatch. That is why NSDPatch must be placed into
       SYS:S/Startup-Sequence and not in User-Startup.

       Alternatively, you can run the included Installer-Script
       "Install", which does a quick installation of NSDPatch.

    5. Reboot and watch the messages that are output by NSDPatch.
       These messages tell you what NSDPatch does. If you can't
       agree with them in some way, go back to 3.

    6. Try NSDQuery on patched devices to check if everything was
       successful. If you encounter problems that can't be fixed
       by going back to 3., check B and C.
       Please report all problems to the author with the device
       names and versions that cause the problems!

    7. Assuming there were no problems, add the "QUIET" option to
       the NSDPatch line in your startup.

    8. That's it. This is the end of a successful installation.


  B. SPECIAL INSTALLATIONS

    1. You may have 3rd party devices which don't support
       IOERR_NOCMD correctly. This means that the driver will not
       reject unknown commands with IOERR_NOCMD, but either crash
       or do very strange things instead. In that case, use the
       IOERRNOCMD option for the respective patch configuration. No
       devices of this type can be named at this time. If you want
       to boot from such a device, read the description of the
       RDBUNIT option carefully. If you encounter such a device,
       please report it to the author.

    2. You may have a trackdisk like device supporting the 3rd
       party TD64 command set. In that case, use the TD64 option
       for the respective patch configuration. By using the
       TD64 option, the general NSD 64 bit commands will be
       rerouted to the already existing TD64 functionality instead
       of being emulated via HD_SCSICMD. Current Guru-ROM's and
       Phase 5 SCSI devices may support TD64. No exact versions can
       be named at this time.

    3. NSDPatch can be invoked multiple times to install more
       patches. Installed patches cannot be changed without a
       reboot.

    4. You can invoke NSDPatch with a config file that doesn't
       actually patch anything but only uses the ACTIVATE and
       RDBUNIT features of NSDPatch. This is considered a positive
       side effect of the NSDPatch design.

    5. You may have a SANA2 device that can't handle a NULL
       ios2_BufferManagement pointer on startup. If you have one of
       those, you'll get enforcer hits with most likely an access
       to address 0 first on a check with NSDQuery. In that case,
       specify the SANA2MAGIC option in the configuration.


  C. TROUBLE SHOOTING

    1. In the unlikely case that NSDPatch crashes your machine on
       the first invocation, you may want to

        - reduce the configuration file to a single line, e.g. for
          parallel.device to make testing easier.

        - check your system for any virus

    2. If you are not sure if a patch was successful, use the
       NSDQuery tool to check up on that device.

    3. If multiple calls to NSDQuery while a device is in memory
       reveal that the reported io_Device value changes for every
       invocation, NSDPatch will not be able to patch this device
       for any openers that opened the device before NSDPatch was
       installed. This is not a bug in NSDPatch.

    4. If NSDQuery behaves strangely on any device, patched or not,
       please report the exact circumstances, including all
       configuration and version information for your Amiga.


Contact
-------

If you have any comments on NSDPatch, please send them to:

    Heinz Wrobel
    Karlstr.16
    82131 Gauting
    Germany
    <heinz@hwg.muc.de>


Implementation
--------------

This may not be very interesting to most readers as it hints at
some technical details. NSDPatch hooks itself into the exec.library
OpenDevice() function. It will patch any opened device that should
be patched and "preprocess" requests sent to it. This way, the user
software sees an NSD device and the device itself will not have to be
reworked in strange device specific ways. Devices patched like this
can still be expunged and reloaded freely. The permanent NSDPatch
footprint in memory is about 3KB plus memory for configuration data
for each device to be patched. NSDPatch does not need to be started
in the background and it does not use any ugly SegList splitting
hacks or similar stunts. NSDPatch should also be compatible to all
debugging tools.


History
-------

43.9
    - Should work with >=V37 now.
    - Supports device mapping now. Implementation of this feature
      has been funded by ATL, Inc.

43.8
    - Reduced stack usage during OpenDevice() patch by about 32
      bytes. The patch needs about 68 bytes now during OpenDevice().
    - The SANA2MAGIC did not work very well. There was a problem in
      handling paths. So it often did not even get activated.

43.7
    - There was a bug in the Version/Revision recognition.
      NSDPatch patched too much at times. This should not have
      hurt, though.
    - Reduced processing time in OpenDevice() a little.
    - Mixing different versions of NSDPatch should not cause any
      harm now.
    - Added new PatchInfo option that tells you about NSDPatch
      activities. Note: This option is more of a debugging hack!
    - More patch lines.

43.6
    - Now supports LVO's that can't normally be SetFunction()'ed.
    - Now supports version specific patches correctly. The override
      general patches.
    - Now supports special SANA2MAGIC for callback handling of old
      devices.
    - Now checks the default patch file DEVS:NSDPatch.cfg
      automatically, if none has been specified.
    - The config file is no longer named v40.nsdpatchcfg. It now
      already has the default name and also has a C= version
      string.

Acknowledgements
----------------

Some were very directly involved in thinking up and testing
NSDPatch. Here is a list in no particular order:

    Olaf Barthel
    Bernhard Möllemann
    Michael van Elst
    Angela Schmidt
    Klaus Burkert
    Joanne Dow

Thank you.

Heinz Wrobel
