Wikis > AHCI > Troubleshooting

Troubleshooting the OS2AHCI Driver

This page contains instructions for troubleshooting and capturing log files.

Things to check before opening a ticket if you have problems

  • Make sure your problem is not listed in the list of Known Issues and Limitations below.
  • Make sure you are using the latest version of a supported driver. Only official drivers distributed by Arca Noae are supported. Any other builds from other sources are not supported.
  • Make sure you are using an official supported kernel.
  • Make sure you are using an official supported loader that goes with the official supported kernel you are using.
  • If you have a PSD installed, make sure it is the latest version and that you are not using any unnecessary switches.

Known Issues and Limitations

  • A maximum of 8 adapters is supported.
  • Hot swapping is not supported

If you open a ticket, additional information will almost always be necessary. You can save a lot of time by always attaching the log file created by the TestLog program to your ticket when you open it, rather than waiting for the developer to ask for it.

If your system system boots successfully either a Startup Debug Log or a Runtime Debug Log will be required. If the system won’t boot or you encounter a trap, a Trap Dump (system dump) or a Serial Debug Log are required. The developer will tell you which type of log is required.

Warning about disk geometries and OS2AHCI versions prior to 1.31

OS2AHCI versions prior to 1.27 ignored LVM geometry information on the disk and in many cases reported the wrong disk geometry to the OS. This has the possibility of causing LVM sectors to be written in the data area of the disk causing data corruption. Also since wrong disk geometries may have been reported to the OS, the disk may be partitioned incorrectly or incorrect LVM information may have been written to the disk. If you used a version lower than 1.27 to do LVM operations on the disk, you should check your disk for these errors. These disks may not be compatible with fixed versions of OS2AHCI (1.31 and higher).

OS2AHCI versions prior to 1.31 did not calculate disk geometries correctly for some hardware. Although not as serious as the problems in versions prior to 1.27, these versions can also cause incorrect LVM information to be written to the disk. This may make some disks incompatible with fixed versions of OS2AHCI (1.31 and higher).

Disk geometry errors are extremely difficult to solve. It is easy to assume that the fixed drivers are broken just because they work differently than the older versions. In fact it is the older versions that are known to be defective and the new versions (1.31 and higher) are working correctly.

In some cases the only way to “fix” the disk is to backup your data using the old driver, install the current fixed driver, wipe the disk, repartition the disk, and then restore your data. In other cases is it enough to remove erroneous LVM data and recreate correct LVM data. However, unless you can know for sure that you have found all of the erroneous LVM sectors on your disk, the only way to be absolutely certain your disk is not corrupted is to wipe it and start over using a known good driver. Then, once you have clean working system, if you ever boot with a version of OS2AHCI prior to 1.31, you must assume that the older driver has corrupted your disk again and you have to start over again.

Capturing a TestLog log file

If you don’t already have the current version of the TestLog program, you can download it here: Get TestLog

Open a command window and execute the testlog command:

testlog ahci

Attach the created log file to your ticket. Do not ZIP the log file.

Setup for a Startup Debug Log

A startup debug log is for a problem that occurs on startup, rather than for a problem that occurs after the system has been running for a while.

To setup the system to capture a startup debug log, do the following:

  • Edit your config.sys and add the following parameters to os2ahci.add:
  • Reboot the machine.
  • Capture the Debug Log.

Setup for a Runtime Debug Log

A runtime debug log is for problems that occur after the system is up and running. It is not for problems that occur at startup.

To setup the system to capture a runtime debug log, do the following:

  • Edit your config.sys and add the following parameters to os2ahci.add:
  • Reboot the machine.
  • Do whatever you need to do to trigger the problem.
  • Capture the Debug Log.

Capturing a Debug Log

To capture Debug Log (Startup or Runtime), you must have the TestLog program available in your path or in the current directory.

To capture the debug log on a system that will boot:

  • Open a command prompt window.
  • If necessary, change directory to where the TestLog program is.
  • Type the following command:
    testlog ahci
  • Attach the log file that is created to your ticket. Please do not zip it.

If your system won’t boot or for some reason you cannot run the TestLog program, you can capture just the AHCI portion of the log using the following method. It is always better to use the TestLog program if possible since it provides much more information.

  • Open a command prompt window.
  • Type the following command:
    copy os2ahci$ ahci.log
  • Attach the log file that is created to your ticket. Please do not zip it.

Beware that capturing a Debug Log clears the debug log buffer. Once you capture the log, that log data is cleared and new log data fills the buffer. Therefore you can only capture the log once. Do not try to run the TestLog program more than once.

Creating a Trap Dump

See: How to Get a Trap Dump

Capturing a Serial Debug Log

In order to do this, you need

  • a machine that reproduces the problem and has a supported serial port.
  • a second machine with a serial port that reads the log. The serial port of this machine can be an add-in card or even use a USB to serial adapter if supported by the OS
  • a terminal program such as ZOC, or PMDF running on the second machine
  • a null modem cable to connect the two machines

Perform the following steps:

  • add the parameters /d:2 /c:1 /b:115200 to the os2ahci.add config.sys statement (level 2 debug information and log to com1, 115200 baud)
  • launch the terminal program on the 2nd machine and enable the log-to-file feature
  • reboot the 1st machine
  • reproduce the problem
  • include the log file generated on the 2nd machine in the bug report

Terminal Program on Second Machine

Launch the terminal program and configure it to use the correct port and serial parameters; these are:

  • speed 115200
  • 8 bits
  • Parity: None
  • X-on: On

This is often abbreviated as 115200 8N1.

Under eCS or OS/2, you can use ZOC or the PM Dump Facility (pmdf.exe) as a terminal program, or on a Linux machine you can use minicom and set up the terminal to use a large scroll back buffer (10000 lines or so).

Reboot the 1st machine and watch the terminal window on the 2nd. You should see a detailed log of all it does.

Reproduce the problem and include the log from the 2nd machine in your bug report.

If you see nothing on the second machine:

  • Do both machines use the correct ports? If any of them has more than one serial port, try them all in all possible combinations.
  • Is the cable really a null modem cable?
  • Check the command line of os2ahci.add in config.sys contains the appropriate com port designator /c:1 for com1, /c:2 for com2, or you can specify the actual com port address as in /c:3f8.
  • Check that the correct baud rate is specified with the /b switch as in /b:115200 and that it matches the baud rate on the second machine.

If the text is garbled on second machine, make sure serial parameters such as baud rate are correct.

Capturing DFSDISK data

This requires having the DFSee software.

  • Change to the DFSee bin directory.
  • Execute the DFSDISK command. The DFSDISK command will create a collection of files usually named DFSDISKo.*
  • Zip those files it creates and attach the zip file to your ticket.