@DATABASE "ErrorLog" @$VER: ErrorLog.guide 1.1 (5.1.2002) @(C) 1993-2002 by Etienne Vogt @SMARTWRAP @AUTHOR Etienne Vogt @INDEX INDEX @NODE MAIN "ErrorLog Guide" ErrorLog Documentation V1.1 (ErrorLogD 1.5) @{"Introduction : What the hell is this for ?" link Intro} @{"License : Some legal mush you should read" link License} @{"Contact : If you need to tell me how great this is ;-)" link Contact} @{"Installation : How to get this stuff installed on your Amiga" link Installation} @{"Configuration : How to configure this damn thing" link Configuration} @{"Support Commands: New shell commands provided in this package" link Commands} @{"Programming : Information for developpers" link Programming} @{"History : What happened before" link History} @ENDNODE @NODE Intro "Introduction" INTRODUCTION ErrorLog is a package for monitoring device activity (currently disks and networks) on classic AmigaOS systems. It requires AmigaOS 2.04 or higher as well as sysmon.library version 1 or higher (available on Aminet as util/moni/Sysmon115b.lha or from http://mesopk.obspm.fr/vogt/amigasoft.html). Some of the features provided by ErrorLog are : @{CODE} - Monitoring of the activity of disk and network devices. - Logging of device and other system errors (alerts) to disk in binary format, translated by a provided command line utility. @{BODY} ErrorLog has been developped and tested on the following configurations : @{CODE} - A4000T 68060 AGA, 2 Mb Chip 72 Mb Fast, OS 3.9 1 Gb SCSI HD + 9.5 Gb IDE HD - A500 68000 ECS, 1 Mb Chip 1.5 Mb Slow 2 Mb Fast , OS 3.1 20 Mb IDE-XT + 50 Mb SCSI + 115 Mb SCSI HDs - A4000 68040 AGA + CV64/3D (CGfx 3), 2 Mb Chip 16 Mb Fast , OS 3.9 250 Mb IDE + 1 Gb SCSI + 512 Mb SCSI + 4 Gb SCSI HDs - A3000 68030/68882 ECS, 2 Mb Chip 16 Mb Fast , OS 3.5 100 Mb + 2 Gb + 4 Gb + 9 Gb SCSI HDs - A500 68040(PP&S) ECS , 1 Mb Chip 2 Mb Fast16 8 Mb Fast32 , OS 2.1 165 Mb SCSI HD @{BODY} This software is intended for experienced users. In particular, there are no GUI tools available yet; so if you are a mouse-maniac user that don't like typing Shell commands or editing ASCII configuration files, I'm afraid that this software is not for you ;-) . @ENDNODE @NODE License "License" LICENSE ErrorLog is Freely Distributable Copyrighted Software (FreeWare). It may be freely copied as long as it is kept intact. It may not be sold under any guise. I don't want others to make money out of my work. Distribution MUST BE FREE, except for media costs plus a token amount covering only shipping and handling. Inclusion of this archive on a CD-ROM compilation of freely distributable software is allowed provided that the retail price of this CD-ROM is not greater than 15 Euros. Furthermore, a free copy of this CD-ROM must be made available for me at no charge except shipping costs. Usage and Distribution of ErrorLog is STRICTLY FORBIDDEN to anyone affiliated with MICROSOFT CORPORATION or its subsidiaries and to people working in the design, production or sale of any kind of WAR WEAPONS. This software is provided "as is" without any warranty, either expressed or implied. By using this software, you accept the entire risk as to its quality and performance. Especially, as this software patches some system functions, it can not be guaranteed that it will continue to work with future operating system versions. @ENDNODE @NODE Contact "Contacting me" CONTACTING THE AUTHOR I can be currently reached by E-Mail at the following addresses: Etienne.Vogt\@obspm.fr Updates to ErrorLog and my other Amiga products (like Sysmon or vdisk.device) are available from my web page at the address http://mesopk.obspm.fr/vogt/amigasoft.html and also on Aminet for the latest release versions. Bug reports should include the complete hardware and software configuration, including any third party software that was running in the background. The Output from 'ShowConfig' and 'ShowSys' may be useful. If you have any question or suggestion about this software, feel free to send me E-Mail. @ENDNODE @NODE Installation "Installation" INSTALLATION @{CODE} - Copy the support commands in the C/ subdirectory of the distribution archive to your C: directory or anywhere else in your search path. - Copy the daemons in the D/ subdirectory somewhere on your system partition (may be the same place as the commands). - Copy the configuration file template ErrorLogD.config in the S/ subdirectory to your S: directory or the place where you usually keep such ASCII configuration files and edit it to match your device configuration as explained in the @{"Configuration" link Configuration} section. - Edit your S:Startup-Sequence or S:User-Startup file to start the binary error logger daemon @{"BinLogD" link BinLogD} and the device error monitoring deamon @{"ErrorLogD" link ErrorLogD}. Both should be started with 'Run <>NIL:' after the DOSDrivers have been loaded as some devices may fail to open otherwise. - Wait for disk activity to finish and reboot your Amiga. If error messages are displayed during boot, you have an error in the ErrorLogD.config file (a device referenced in the config file may not be accessible for example). - Once the system is successfully booted, try the 'devinfo' support command in a shell window to see which devices are being monitored. Refer to the @{"Support commands" link Commands} section for more information. @{BODY} @ENDNODE @NODE Configuration "The ErrorLogD Configuration File" ERRORLOGD CONFIGURATION The configuration file ErrorLogD.config is used to set up the ErrorLogD daemon and declare the devices that should be monitored at startup time. Other devices may be added later through the @{"LogDevice" link LogDevice} support command. The file is usually located in the S: directory. If you want to put it somewhere else, you have to add the complete path to the file as argument to the @{"ErrorLogD" link ErrorLogD} command in the Startup-Sequence. Any line in the file beginning with ';' is considered to be a comment line and is ignored. The configuration parameters currently available are : @{CODE} - DAEMONPRI : This keyword in the only one that can appear outside of a DEVICE/END construct. It specifies the exec task priority at which the ErrorLog.daemon process should run. The valid values range from 0 to 20 with 6 being the default. For best performance, the priority value should be lower than these of the device drivers (typically around 10) but larger than those of interactive processes or console handlers (typically between 0 and 5). - DEVICE : This keyword starts the description of a device that should be monitored. Its argument is the name by which the monitored device will be known. This name is limited to 8 characters in size. The monitoring is done on the basis of exec device units, so per partition logging on multi- partitionned disks is not possible for instance. The name you choose here is arbitrary but using the AmigaDOS device name for non partitionned or single partitionned disks seems natural. For multi-partitionned disks, you could use the name of the biggest partition or something referring to the unit number like IDE0 or SCSI6. - DEVNAME : This keyword specifies the exec device name for the unit to be monitored, like scsi.device or trackdisk.device. It is mandatory. - DEVUNIT : This keyword specifies the exec device unit number. It is also mandatory. - DEVFLAGS : This keyword specifies the exec device flags value. Most devices will happily take the default value of 0. - DEVTYPE : This keyword specifies the exec device type as defined in the NSD (New Style Devices) specification. Note that ErrorLogD does not currently send an NSCMD_DEVICEQUERY command to get this value so it should be specified here even if the device is NSD compatible. Valid types are UNKNOWN, GAMEPORT, TIMER, KEYBOARD, INPUT, TRACKDISK CONSOLE, SANA2, AUDIO, CLIPBOARD, PRINTER, SERIAL, PARALLEL or their numeric value as defined in the devices/newstyle.h include file. The default is UNKNOWN. Note however that only TRACKDISK and SANA2 type devices are currently supported. - DEVSUBTYPE : This keyword is used to finer define the type of device. It is only used for TRACKDISK-like devices where it can be set to the device types defined in the SCSI specifications. The ErrorLog formatter command will use this value when interpreting SCSI-direct commands. The values currently defined are: 0: Direct-access devices (disks), this is the default value 1: Sequential-access devices (tape drives) 2: Printer devices 3: Processor devices 4: Write-Once Read-Multiple devices 5: CD-ROM devices 6: Scanner devices 7: Optical memory devices 8: Medium changer devices 9: Communication devices - IOREQSIZE : This keyword specifies the size in bytes of the IORequests that are normally sent to this device. It defaults to the size of a standard IOStdReq structure (48 bytes). Commands that are documented to need a bigger size than the one generally used for this type of device (such as the trackdisk ETD_ commands) will be handled automatically. - LOGPRI : This keyword specifies the node priority at which the DoomNode describing this unit will be inserted in the list. Units that are fast and that receive many IORequests should be given a value higher than the default of 0. - LOGERRORS : This keyword specifies if errors occuring on this unit should be logged. There is currently no mechanism to specifically disable logging for certain type of errors so you either get all or none. Set this to OFF for devices you wish to monitor for activity but which may generate a lot of errors in normal operation, such as some removable cartridges (SCSI CDROMs with the OS3.5 CacheCDFS will generate a bunch of errors on each media change for example). It defaults to ON. - END : This keyword ends a device unit description. It takes no argument. @{BODY} @ENDNODE @NODE Commands "Support Commands" SUPPORT COMMANDS These support commands should be installed in your C: directory or some other directory in your shell search path. They can only be used from the Shell. The commands currently provided are: @{CODE} - @{"BinLogD" link BinLogD} - @{"ErrorLogD" link ErrorLogD} - @{"ErrorLog" link ErrorLog} - @{"DevInfo" link DevInfo} - @{"LogDevice" link LogDevice} @{BODY} @ENDNODE @NODE BinLogD "BinLogD" BinLogD: BinLogD is the binary error logger daemon. It should be called at system startup time via a 'Run <>NIL:' command from the Startup-Sequence or User-Startup script file. @{CODE} Usage : Run <>NIL: BinLogD FILE,PRI=PRIORITY/K/N FILE: Name of the file the error event logs will be written to. Defaults to DEVS:ErrorLogFile.sys PRIORITY: Task priority of the daemon process. Defaults to 3. @{BODY} The purpose of this utility is to write system error events to a disk file in compact binary format. The events currently logged are device error reports generated by the device monitoring daemon @{"ErrorLogD" link ErrorLogD} and alert (gurus) reports generated by sysmon.library. BinLogD also generates its own startup event messages. To format the events in the error logfile, use the @{"ErrorLog" link ErrorLog} formatting utility. Note that BinLogD is not currently very smart about writing the events to disk (no internal buffering is done for example) so it may be wise to put the logfile in some other place than the default. Also, choosing a scratch partition is recommanded since a crash while the daemon is writing an event might lead to an invalidated disk. @ENDNODE @NODE ErrorLogD "ErrorLogD" ErrorLogD: ErrorLogD is the device monitoring daemon. It should be called at system startup time via a 'Run <>NIL:' command from the Startup-Sequence or User-Startup script file. @{CODE} Usage : Run <>NIL: ErrorLogD CONFIGFILE,PRI=PRIORITY/K/N CONFIGFILE: Name of the @{"Configuration file" link Configuration}. Defaults to S:ErrorLogD.config PRIORITY: Task priority of the daemon process. Defaults to 6. @{BODY} ErrorLogD patches the BeginIO() vector of selected devices to monitor their I/O activity (currently only disk and sana2 network devices are supported). It makes a copy of each IORequest received and sends the copy to the device driver after changing the reply port to ErrorLogD's own port. On completion of the I/O operation, ErrorLogD receives the completed IORequest and processes its result before copying it back to the original request which is then sent back to its originator. This process is completely transparent to the sender of the request, except for a little overhead (also devices that can process some commands from supervisor mode, like the timer.device, can't be monitored at all). A counter of the total number of operations done on each monitored unit is maintained and can be displayed by the @{"DevInfo" link DevInfo} command. When an IORequest returns with a non zero Io_Error field and error logging for this unit is enabled, a device error message will be constructed and sent to the @{"BinLogD" link BinLogD} error logger daemon. A copy of the failed IORequest will be included in the error message along with some other relevant information. These messages can be translated by the @{"ErrorLog" link ErrorLog} formatting utility. As a bonus for programmers, ErrorLogD also checks for premature reuse of active IOrequests on monitored units and will throw an AN_IOUsedTwice recoverable alert if such abuse is detected (except for commands like TD_ADDCHANGEINT which don't follow this rule and are not counted as pending requests). @ENDNODE @NODE ErrorLog "ErrorLog" ErrorLog: ErrorLog is the error event formatting utility. It translates events recorded in the error logfile by @{"BinLogD" link BinLogD} into human readable text output. @{CODE} Usage : ErrorLog SELECT/M,FROM/K,SINCE/K,FULL/S SELECT: Selects events to be displayed. You can specify device/unit names as given in the ErrorLogD configuration file to select errors from the corresponding device/unit, 'alert' to display system alerts or 'startup' for the BinLogD startup messages. The default is to select all events. FROM: The name of the error logfile to read. Defaults to the active BinLogD logfile which name is saved in the 'ErrorLogFile' environment variable. SINCE: Filters events by date. Only events more recent than the specified date will be selected. This selection criterium combines with the SELECT keyword in logical AND mode (both criteria must be met for the event to be displayed). FULL: Enables full display, which shows some additional fields that may be useful for debugging purposes. @{BODY} ErrorLog knows about all the standard commands and error codes for sana2 and trackdisk type devices, as well as the NSD and TD64 extensions. It also knows about the alert codes defined in the system include files (exec/alerts.h) as well as some third party alert codes such as those used in sysmon.library or mmu.library for example. It will now also display the SCSI command and sense data on a failed HD_SCSICMD trackdisk command. The current version knows about the SCSI-2 opcodes and additional sense codes. The opcodes are translated according to the DEVSUBTYPE config option for that unit which is to be set to the SCSI-2 device type. Some examples of error messages display are shown below. @{CODE} *** Error entry 0 (Version 2) *** Logged on samedi 13-mai-00 15:47:39 BinLogD Startup 68060 *** Error entry 1 (Version 2) *** Logged on samedi 13-mai-00 15:48:19 Device Error DF0, trackdisk.device Unit 0 Calling Task : AmigaShell_9 (checkdisk) Device Type : 05 NSDEVTYPE_TRACKDISK Device SubType : 00 Direct-access Device IORequest size : 0030 Operation Count: 00000024 36 IORequest(s) completed for this unit Error Count : 0001 1 Error(s) for this unit IORequest structure io_Command : 0002 CMD_READ io_Error : 19 TDERR_BadSecSum (Bad sector data checksum) io_Actual : 00002000 16 block(s) transfered (at 512 bps) io_Length : 00002C00 22 block(s) to transfer (at 512 bps) io_Data : 082D1BD8 io_Offset : 0004D000 Block number 616 (at 512 bps) *** Error entry 11 (Version 2) *** Logged on vendredi 04-fév-00 09:31:00 Device Error FDH0, scsi.device Unit 3 Calling Task : HDToolbox Device Type : 05 NSDEVTYPE_TRACKDISK Device SubType : 00 Direct-access Device IORequest size : 0030 Operation Count: 000000F4 244 IORequest(s) completed for this unit Error Count : 000B 11 Error(s) for this unit IORequest structure io_Command : 001C HD_SCSICMD io_Error : 2D HFERR_BadStatus (Bad SCSI status or sense) io_Actual : 00000000 io_Length : 00000022 io_Data : 082A1E04 io_Offset : 00000000 SCSICmd structure scsi_Data : 00000000 scsi_Length : 00000000 scsi_Actual : 00000000 scsi_Command : 082A1E58 scsi_CmdLength : 0000000A scsi_CmdActual : 0000000A scsi_Flags : 02 WRITE, AUTOSENSE scsi_Status : 02 CHECK CONDITION scsi_SenseData : 082A1D04 scsi_SenseLength: 000000FF scsi_SenseActual: 00000030 SCSI Command Operation Code : 2F VERIFY(10) Parameters : 00 00 00 00 00 00 FF FF Control Byte : 00 SCSI SenseData Error Code : F0 VALID, CURRENT ERROR Segment Number : 00 Sense Key : 03 MEDIUM ERROR Information : 0000008C Add. S. Length : 28 Comm. Sp. Info : 00000000 ASC ASCQ : 1000 ID CRC OR ECC ERROR FRU Code : 00 Sense-Key Sp. : 800012 Add. S. Bytes : 30 2F BB 1C 01 02 00 00 40 01 03 10 00 3C 20 E0 00 00 FD 7A 7F 56 BA 14 20 00 20 00 79 9D *** Error entry 1 (Version 2) *** Logged on dimanche 25-juin-00 18:37:13 DeadEnd Alert 68060 Guru Meditation: 80000003 ACPU_AddressErr (Odd address error) Current Task : 082759A8 AmigaShell_10 (crashtest) SubSystem : N/A General Error : N/A Alert Object : N/A Integer registers D0-D7 = 8D3E0000 0001020B 32230000 61A80827 682C0000 0001020C 33CB0208 C1658000 A0-A7 = 00030827 682C0838 1FC00801 F244082C C88C0838 8160082C C8A00800 08800800 PC = 00F80C14, SR = 2010 Floating Point registers FP0-FP1 = 7FFF0000FFFFFFFFFFFFFFFF 7FFF0000FFFFFFFFFFFFFFFF FP2-FP3 = 7FFF0000FFFFFFFFFFFFFFFF 7FFF0000FFFFFFFFFFFFFFFF FP4-FP5 = 7FFF0000FFFFFFFFFFFFFFFF 7FFF0000FFFFFFFFFFFFFFFF FP6-FP7 = 7FFF0000FFFFFFFFFFFFFFFF 7FFF0000FFFFFFFFFFFFFFFF FPCR = 00000000, FPSR = 00000000, FPIAR = 00000000 System registers USP = 08388158, SSP = 0800229E VBR = 08124338, SFC = 00000002, DFC = 00000005 CACR = A0808000 ITT0 = FFFF6040, ITT1 = FFFF6040, DTT0 = FFFF6040, DTT1 = FFFF6040 TC = 00008000, URP = 080F0000, SRP = 080BC000 PCR = 04300501, BUSCR = 00000000 @{BODY} @ENDNODE @NODE DevInfo "DevInfo" DevInfo : This command displays statistics about a particular or all monitored devices/units, such as the total number of I/O operations completed, the number of I/Os still pending or the number of errors seen so far. @{CODE} Usage : DevInfo DEVICE,FULL/S DEVICE: Name of a monitored device/unit which statistics should be displayed, as given in the ErrorLogD configuration file. The default is to display statistics for all monitored units. FULL: Enables display of additionnal information which is mostly of interest for debugging purposes. @{BODY} Some example display is shown below @{CODE} VD0 : Device vdisk.device, Unit 0, enabled, error logging on Operations completed : 122 Operations pending : 0 Error count : 0 DH0 : Device 2nd.scsi.device, Unit 0, enabled, error logging on Operations completed : 11160 Operations pending : 0 Error count : 0 DH3 : Device scsi.device, Unit 0, enabled, error logging on Operations completed : 197 Operations pending : 0 Error count : 0 CD0 : Device scsi.device, Unit 1, enabled, error logging off Operations completed : 1103 Operations pending : 0 Error count : 0 DZ0 : Device 2nd.scsi.device, Unit 6, enabled, error logging on Operations completed : 2451 Operations pending : 0 Error count : 0 DF0 : Device trackdisk.device, Unit 0, enabled, error logging on Operations completed : 254 Operations pending : 0 Error count : 0 DF1 : Device trackdisk.device, Unit 1, enabled, error logging on Operations completed : 397 Operations pending : 0 Error count : 0 @{BODY} @ENDNODE @NODE LogDevice "LogDevice" LogDevice : This command allows to add or remove a monitored unit dynamically and tu turn on or off error logging, so you can for example turn it off when accessing a known bad disk. @{CODE} Usage : LogDevice DEVICE/A,DEVNAME/K,UNIT/K/N,FLAGS/K/N,PRI=PRIORITY/K/N, IOSIZE/K/N,TYPE/K,SUBTYPE/K,ON/S,OFF/S,REMOVE/S DEVICE: The name by which the device/unit is or will be known by ErrorLogD. See the @{"Configuration file" link Configuration} for more information. DEVNAME: The name of the exec device that is driving this unit, like "scsi.device". It must be specified when adding a new monitored device/unit. UNIT: The exec unit number. It must be specified when adding a new device/unit. FLAGS: The flags parameter for the OpenDevice() call. The default value of 0 is generally OK. PRIORITY: The list priority of the DoomNode that will describe this monitored unit. Fast units like networks cards or ram disks should get positive value, while slow floppy disks should have negative one. Defaults to 0. IOSIZE: The size of the IORequest stucture that this device normally needs. Defaults to the size of a standard IOStdReq structure, 48 bytes. TYPE: The type of device as specified by the NSD standard, in string or numeric form, like SANA2 or TRACKDISK. Defaults to UNKNOWN. SUBTYPE: For TRACKDISK-like device units, the SCSI-2 device type in numeric form (see the @{"Configuration file" link Configuration}). ON: Turns on error logging for the specified device/unit. All errors will now be passed to BinLogD. OFF: Turns off error logging for the specified device/unit. All errors returned will now be ignored by ErrorLogD and just passed back to the sender of the IORequest. REMOVE: Removes the specified device/unit from the list of monitored units. ErrorLogD will no longer do any monitoring for this unit. This will not work if IORequests are still pending. @{BODY} It you want to monitor some unit that may not always be available at startup, like external disks, it is recommanded to not add them to the configuration file as it would put up an error message if they are turned off at system startup. Instead, check for the disk presence in the User-Startup script (with 'Assign >nil: disk: exists') and execute a LogDevice command to start monitoring if the disk is connected. @ENDNODE @NODE Programming "Developper Information" INFORMATION FOR DEVELOPPERS When started, ErrorLogD adds a high priority public semaphore called "ErrorLog.HellGate". The SignalSemaphore structure is extended to form the so-called HellGate structure which is described in the errorlog.h include file. You MUST obtain the HellGate semaphore via ObtainSemaphoreShared() before peeking at any field of this structure. Furthermore, only shared read access is allowed, exclusive write access being reserved to the ErrorLog.daemon process itself. Also, you can't perform any I/O operation safely while holding the semaphore as it may result in a deadlock. Information about monitored units is kept into DoomNode structures which are linked into the hg_DoomList list in the HellGate structure. For an example of accessing these structures, see the source code of the DevInfo support command that is provided in the archive. There is currently no public API for the binary error logger BinLogD. This will probably be provided as part of a future version of sysmon.library. @ENDNODE @NODE History "Version History" CHANGES @{CODE} @{B}V1.5@{UB} Added display of SCSI command and sense data in ErrorLog formatter. Added device subtypes (used for SCSI device type specifications). Some minor bugfixes. @{B}V1.4 beta@{UB} First public beta release of ErrorLog. @{BODY} @ENDNODE @NODE INDEX "Index" @{CODE} B... @{"BinLogD" link BINLOGD} C... @{"Contacting the author" link CONTACT} @{"Configuration File" link CONFIGURATION} D... @{"Developper Information" link PROGRAMMING} @{"DevInfo" link DEVINFO} E... @{"ErrorLog" link ERRORLOG} @{"ErrorLog Guide" link MAIN} @{"ErrorLogD" link ERRORLOGD} I... @{"Index" link INDEX} @{"Installation" link INSTALLATION} @{"Introduction" link INTRO} L... @{"License" link LICENSE} @{"LogDevice" link LOGDEVICE} S... @{"Support Commands" link COMMANDS} V... @{"Version History" link HISTORY} @{BODY} @ENDNODE