$Id: README.FIRST 1.20 1997/12/15 18:55:56 heinz Exp $ NSDPatch ======== What is NSDPatch? ----------------- NSDPatch will hook into the OS (V37+, 2.04+) and patch almost arbitrary types of Exec 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 does not affect DOS devices like PAR: in any way. NSDPatch only handles Exec devices. 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 AI V43 FFS, you can use partitions >4GB on disks >4GB. NSDPatch also includes RDB mount functionality to support special configurations. NSDPatch also fixes some bugs with certain devices like the V40 mfm.device or incompatibilities of, e.g., a JAZ drive and V40 scsi.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 or buggy 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 and convenient fixes 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 or www.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 ------------ **************** *** READ IT! *** **************** There is an Installer-Script "Install" included, that does a quick installation and setup of NSDPatch, including its configuration. If you go this way, you may still want to read below about what happens. If you don't want the 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 including entries for devices known to be broken. When you have looked it over and want to boldly go where quite a few now have gone before, proceed like this: A. BASIC INSTALLATION 1. Make a copy of the file NSDPatch.cfg, 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 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. SPECIAL NOTE: If you map trackdisk.device units, you must start any "noclick" hack _after_ SetPatch but _before_ 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 below. 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 line. 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 official 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 - try NSDPatch with an empty configuration file to verify basic installation compatibility. - 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 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. 5. The NSDPatch 64 bit disk emulation capabilities or the FIXSCSIUPDATE option may not work as expected on an IDE scsi.device that has been patched by atapi.device. This is not a bug in NSDPatch. D. ADDING NEW PATCH LINES 1. The safe solution is emailing a copy of the device in question to the author. He will generate a suitable patch line to be placed into NSDPatch.cfg. The quick and dirty solution is outlined below. 2. First make sure that everything important is saved because the tests for what you need may crash the system. If possible, run Enforcer. 3. Try NSDQuery on the device. If your Amiga crashes or severly misbehaves, you will need the IOERRNOCMD option! If you get a report that the device is NSD, you don't need to patch it. 4. Check NSDPatch.cfg for an existing similar line and make a copy, changing the name appropriately. If you have, e.g., magicscsi.device, you may want to use the line for scsi.device as first approximation and put the name magicscsi.device into the copied line. For, e.g., mynewaudio.device, you would take the line for audio.device as example. 5. Put the new line with the device's name into NSDPatch.cfg. If needed according to 3., add the IOERRNOCMD option if it isn't already there. 6. Start NSDPatch and try NSDQuery again. Now, the device should respond as NSD device, based on the new config line. 7. Never change too many patch options at once. After changing a patch option, you must reboot for it to take effect. Read the descriptions in NSDPatch.cfg before using options. 8. In case of any more problems, contact the author. 9. If the patch line works well and solves your problems, please forward it to the author. Contact ------- If you have any comments on NSDPatch, please send them to: Heinz Wrobel Karlstr.16 82131 Gauting Germany 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 then 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 4KB 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.17 - As it turns out, there are devices that fail to open, do not set io_Device and return with no error. NSDPatch "fixes" this now to avoid crashes and returns IOERR_OPENFAIL in that case. 43.16 - Even more patch lines added. Now a new option INTBEGINIO is available to make NSDPatch really safe for devices where BeginIO() may be called from within interrupt code. This affects the patch lines for audio.device and timer.device. The RDB late mount functionality will no longer complain about already existing DOS mounts if MOUNTANY has been specified. This makes using patterns easier. 43.15 - The version/revision match code ignored general patch requests. This made it impossible to patch, e.g., an ISNSD device with FIXSCSIUPDATE. 43.14 - Cleanup for FIXSCSIUPDATE option. Will ignore an error on internal handling now just like scsi.device. This keeps FORMAT happy. 43.13 - Cleaned up some of the 64 bit emulation code. A few SCSI CDB's are set up better now. Added FIXSCSIUPDATE option. It will turn CMD_UPDATE for scsi.device into something that does no longer conflict with JAZ drive behaviour even though it should still work as expected for other devices. NSDPatch will use significantly less stack in its BeginIO patch for patched devices in the general case now. 43.12 - NSDPatch no longer pops up requesters when activating DOS devices. Whenever you specify QUIET as option, NSDPatch will no longer complain about already mounted entries when using the RDB functionality. More updates to the config file. SINLEPATCHONLY is now the default option as it tends to be a lot more compatible to many debug tools commonly used with AmigaOS. To get the the old behaviour back where the device specific patch is reinstalled for each and every OpenDevice, you can use the new TRYMULTIPATCH option. Note that with other tools patching into the same vectors you may cause infinite loops when using this option! 43.11 - Added MOUNTANY option for RDB support. This facilitates RDB mount magic by allowing access to any partition, not just partitions not marked as automount. It is meant for the advanced user. Added PATCHCONFIGLINE command line option. You can use NSDPatch with a single simple config line. It will not read in a config file then unless you also specify one. The default DEVS:NSDPatch.cfg will now only be read if no command line options have been used. Updated the configuration file a little. 43.10 - Added SINGLEPATCHONLY option for device patch lines. With this option, a device will only patched for its initial open call. This fixes interaction with CMD, which will hang in an endless loop without SINGLEPATCHONLY. This again shows how dangerous the use of the exec.library SetFunction() call is. 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