********************************************************************** * PCI BIOS Diagnostic Program (PCITest v2.01) * ********************************************************************** ---------------------------------------------------------------------- The PCI BIOS Diagnostic Program is supplied with all DEC DC21040 and DC1010 chip-compliant Ethernet adapters like the Linksys EtherPCI LAN Card. Instructions from Digital are included below. The Diagnostic program is for low-level technical troubleshooting only, and is not required to configure or use the EtherPCI LAN Card. ---------------------------------------------------------------------- 1.0 INTRODUCTION ----------------- The PCITest PCI BIOS diagnostic performs the following: 1. Verifying that an implemented BIOS correctly supports the features detailed in the PCI Local Bus Specification Rev 2.0 and the PCI BIOS Specification Rev 2.0 (updated 7/20/93) . 2. Providing information about the system under test . 3. Partial testing of hardware devices supporting the PCI bus and connected to it. 4. If a DC21040 or DC1010 chip is present in the system, it is verified that its initialization and configuration space data are compliant with the vendor's specifications. The program supports BIOS call done in real mode, 16-bit protected mode or 32-bit protected mode. The diagnostic covers each of the functions described in the specification besides these which write to the configuration space, since writing to the configuration space of an unknown device may generate inconsistent results or even hang the system. The diagnostic provides run-time switches which control the program flow. These will be described in section 3.0. Problems in the system under test can be identified in the following ways: 1. Detailed error massages provided by the diagnostic. 2. The user can define which tests and sub-tests to apply and which not. 3. An exception handler is set when calls are done in protected mode. This exception handler deals with some of the important exceptions and dumps the CPU registers on to the screen when the exception happens. 4. A log file can be set up which logs all parameters before and after PCI BIOS calls. This log is fall-tolerant as it saves the BIOS call parameters even if the processor hangs as a result of the BIOS call. 2.0 STRUCTURE OF THE DIAGNOSTIC AND TESTS IT PERFORMS ------------------------------------------------------ The configuration space of the PCI devices in a given system can be viewed in three ways: 1. What SHOULD be in the configuration space, which is dependent on the devices physically connected to the bus, the sytem hardware and BIOS implementation . 2. What actually resides in the I/O-space addresses into which the configuration space is mapped (by host bridges). 3. What view is returned after invoking the various PCI BIOS calls. It is our interest that these three views be identical and that they will stand in compliance with the PCI specs mentioned above, and the specs of the various vendors. The diagnostic reads the I/O-space addresses into which the configuration space is mapped, and generates a list of PCI devices in the system. All this is done without using BIOS calls. This view of the system and devices connected to it is compared to results obtained using PCI BIOS calls. If a DC21040 or DC1010 chip is present, the diagnostic checks if its configuration-space data matches what had to be there. In addition, the diagnostic tests the various PCI BIOS calls. After every call the program checks that no register corruption happened. If calls are performed in more than one mode, the results returned from the different modes are compared. We will now describe each of the steps carried out by the program, using the numbering scheme and and titles used by the pre-run menu : 0.0 Preliminary : 0.1 First the diagnostic checks that the machine supports PCI. If it does not, execution is halted. 0.2 The diagnostic searches for memory managers (such as Windows, EMM386, etc.). If any of these is present, execution is halted. This is done for two reasons: 1. A known bug in most versions of EMM386 causes failure of the diagnostic. 2. It is impossible to run the diagnostic using protected mode calls under any memory managers. 0.3 If the BIOS calls were specified to be done in protected mode, the diagnostic searches for the 32-bit enrty point of the PCI BIOS services. If this is not found, the diagnostic halts execution. 1.0 "Reading Configuration Space Using Hardware Mechanisms" . The configuration space of the devices is read using access mechanisms provided by the bus hardware (described in section 3.6.4.1 of the PCI local bus specification). After determining which mechanism is used by the system under test, the configuration space is accessed by applying the necessary switches and reading the machine's I/O space. The diagnostic tries to access all possible devices on all possible busses, and for each device checks all functions it provides (in case of multiple- function devices). A list of all devices found is formed, and it is used as a basis for many of the tests appplied by the diagnostic. If no devices (bridge included) are found, the program terminates execution. If the number of busses or devices found exceeds the parameters bounding them (they can be set, see section 3.2 of this document), they will not be included in the devices' list and the user will be notified. The diagnostic also checks if there are devices which are mapped as more than one physical device on the PCI bus. If this is the case, all instances besides the first are purged (unless the user specifies otherwise. See section 3.2). 2.0 "Verifying Basic Configuration-Space And BIOS Data" . The diagnostic performs the PCI_BIOS_PRESENT BIOS call, and checks if the information it returnes is sensible and if it matches the information obtained in stage 1.0 . Errors found are reported to the user. 3.0 "Printing List Of All Devices On The PCI Bus" . Using the information obtained in stages 1.0 and 2.0, a list of all devices is generated. For each device (or each function in the case of a multiple-function device), its bus, device and function number are output, as well as its characteristics and the 256 bytes of its configuration space. The list is ordered according to bus, device and function numbers. In addition, general data about the system and the BIOS is presented. 4.0 "Verifying Device Access And Format Using Other PCI Bios Functions" . Once the PCI devices have been identified, the diagnostic validates that each listed device can be found using BIOS calls: 4.1 "Checking FIND_PCI_DEVICE PCI BIOS Function" . Using device and vendor IDs of devices found, they are accessed using this BIOS call. 4.2 "Checking FIND_PCI_CLASS_CODE PCI BIOS Function" . Using class codes of devices found, they are accessed using this BIOS call. 4.3 "Checking READ_CONFIG_BYTE PCI BIOS Function" . The diagnostic tries to access each of the devices using this BIOS call, reading the first bytes of the configuration space and checking they relate to the identified device. 5.0 "Checking PCI BIOS Function Boundary Conditions" . The diagnostic performs several BIOS calls which attempt to generate conditions which may cause the BIOS to fail. All errors are reported to the user. These tests include: 5.1 "Boundry Checking FIND_PCI_DEVICE PCI BIOS Function" . For the FIND_PCI_DEVICE call, the diagnostic first determines the minimum (and maximum) valid PCI device id and vendor id which does not appear in the list of PCI devices in the system. Once determined, the test attempts to find the first and the last device with each possible combination of the minimum (and maximum) PCI device id and vendor id. Each call to the BIOS should return that the device could not be found. In addition to these checks, a vendor id of FFFFh is given as an argument which should generate an illegal vendor id error. If the expected results are not generated from the BIOS calls an error message will be generated. 5.2 "Boundry Checking FIND_PCI_CLASS_CODE PCI BIOS Function" . For the FIND_PCI_CLASS_CODE call, the diagnostic first determines the minimum (and maximum) class code which does not appear in the list of PCI devices in the system. Once determined, the test attempts to locate the first and the last device for the minimum (and maximum) class code which was identified. The test procedure expects each BIOS call to fail. 5.3 "Boundry Checking GENERATE_SPECIAL_CYCLE PCI BIOS Function" . For the GENERATE_SPECIAL_CYCLE call, an invalid bus number is selected and a "shutdown" message is passed to the BIOS. The test will generate an error message for the user if the BIOS indicates that the message was sent successfully. 5.4 "Boundry Checking READ_CONFIG_BYTE PCI BIOS Function" . For the READ_CONFIG_BYTE call, a device is selected from the list of PCI devices in the system under test and an attempt is made to read from several invalid offsets. 5.5 "Boundry Checking READ_CONFIG_WORD PCI BIOS Function" . For the READ_CONFIG_WORD call, a device is selected from the list of PCI devices and an attempt is made to read from an invalid offset and an offset which is not word aligned. Any unexpected results will be eturned to the user via an error message. 5.6 "Boundry Checking READ_CONFIG_DWORD PCI BIOS Function" . For the READ_CONFIG_DWORD call, a device is chosen from the list of PCI devices and a read attempt is made from an invalid offset and an offset which is not dword aligned. 5.7 "Boundry Checking INDEX option in PCI BIOS calls" . For the FIND_PCI_DEVICE and FIND_PCI_CLASS_CODE it is verified that the 'Index' (i.e. - Number of devices having a given vendor and device ID or a given class-code) given by these BIOS calls matches results obtained by stage 1.0 . 6.0 "Verifying PCI Bios Read Functions" . 6.1 "Checking Devices' Vendor ID according to different read options" . The diagnostic attempts reading Vendor ID of all possible devices (running over all possible busses and devices), using the three different read calls. Two type of errors are reported in this stage: 1. Any inconsistencies between the calls in the different modes (perhaps implying in some of the calls devices not found by others). 2. New devices found which were not identified in stage 1.0. New devices found are devices whose Vendor Id is not FFFFh. 6.2 "Checking Config Space For Each PCI Device Using READ PCI BIOS calls". The diagnostic verifies that the first 64 bytes of the configuration space for each PCI device can be read using the READ_CONFIG_BYTE, READ_CONFIG_WORD, and READ_CONFIG_DWORD calls. Any inconsistencies between the different methods of reading the configuration space are reported to the user. 7.0 "Verifying DC21040/DC1010s Have Neccesary Characteristics" . If DC21040 or DC1010 chips are found on board, they are checked to be consistent with the vendor's requirements regarding some of the fields in the configuration space. These include: Command, Status, Class Code, Interrupt Line, Interrupt Pin, Configuration Base I/O Address, Configuration Base Memory Address. 3.0 PRE-RUN MENU ----------------- PCITest provides a pre-run menu which offers four windows. The movement between different windows or window-entries is through the arrow keys. Entry and exit to sub-windows is done with 'Enter' and 'Escape' keys. The 'Space' key is used as a toggle key - switching on and off the option on which the cursor is positioned. The following windows are provided: 3.1 Selective Application of Tests (PCITest Window). ---------------------------------------------------- The main window presents the user with the 7 basic stages of testing. The first stage during which the system is analyzed and a list of devices is generated is a must. All other stages can be turned on or off using the Space bar as a toggle key. Some of the tests have a sub-menu attached to them. When the cursor is located on a specified test which is composed of sub-tests (the description of which appears in the previous section), pressing the 'Enter' key will open a window listing the sub tests. These can be turned on or off. When the main test is on, all sub tests will be run. 3.2 Log-File Options and Setting the diagnostic parameters. ----------------------------------------------------------- The log&setup window presents the user with several options: The first enables the user to open a BIOS call log file. This file records the parameters sent to BIOS calls, and those which were returned. The file holds information about the last calls performed (the size of this file is limited). If any critical error happens durind a BIOS call, the offending call and its parameters can be found using the log. The calls will be logged to file "BIOS.LOG". The second option enables the user to log all the program's output (including system information and error messages) in a file. The calls will be logged to file "INFO.LOG". These two log files have quick flushing as to prevent a loss of information in the case of a system hang or buffer corruption. An unwanted result is that using log files substantialy increases the running time of the program, since almost every file operation requires disk access. The user has also the option of setting diagnostic run-time parameters by pressing when the cursor is on the last item of this window. The parameters which can be set are: 1. Maximal number of errors - A limit is set to the number of times an error message of any type will be presented. This excludes only register errors (see next section). 2. Maximal number of register corruption/mismatch errors - A limit is set to the number of two types of register errors: Register corruption occurs when registers which should not have changed after a BIOS call were changed. Register mismatch happens when BIOS calls performed in different modes return different results. This limit relates to the number of such errors to report for EACH one of the different BIOS Calls. 3. Maximal number of busses - This sets a limit to the number of busses from which devices appear in the program's devices' list. 4. Maximal number of devices - This sets a limit to the number of devices which can be included in the program's devices' list. The limit imposed by the two last items mentioned is due to the fact that as a result of system errors, there are devices which appear to be mapped as many devices in the PCI bus. In order to prevent clogging of the test, there is a limit. 5. Purge seemingly multiple instances of PCI devices - When devices are found to have an identical configuration space we suspect that only one physical device of this type is actually in the system and all its other dummy instances are not included in the program's devices' list. The default is purge, but the user may wish not to purge. Whenever multiple instances of a device are purged, the user is notified. 3.3 Modes of Operation (MODE Window). ------------------------------------- This window lets the user specify in which mode/modes of operation the BIOS calls should be performed. These include Real mode, 16-bit Protect mode and 32-bit Protect mode. At least one of the running modes must be active. When more than one is active, all BIOS calls are performed in all active modes. 3.4 Activation (GO Window). --------------------------- After selecting from the various options the user runs or quits the program. 4.0 TROUBLESHOOTING -------------------- Several troubleshooting notes: 0. If the diagnostic stops working in the middle of a test, the following can help to pinpoint the cause of the failure: 1. Changing the run-menu options can help. One can selectively apply tests in order to isolate the problematic point. One can also alternate the running modes and change run time parameters. 2. The BIOS-calls log can be activated (in the run menu) and offending BIOS calls can be isolated this way. 3. The exception handler dumps onto the screen a dump of the CPU registers and in this case one can see the CS:EIP, selector values and other relevant information. 1. The diagnostic is best run without any memory managers or unneccesary device drivers. The program identifies most memory managers, and in this case it halts execution. It is highly advisable to boot the machine using the basic DOS boot, and have the floppy disk as a current directory when running the diagnostic. 2. It might be necessary to enlarge the number and size of the DOS stacks. This is done using the STACKS command in the CONFIG.SYS file. An advisable value is: " STACKS = 32,256 " . 3. The program requires free memory in the range of 10K-100K for storing run-time information on the sytem and devices connected to it. 4. For support or explanation of the diagnostic output please contact: YISHAI@JEREMY.ENET.DEC.COM or- NIMROD@JEREMY.ENET.DEC.COM. 5.0 EXPLANATION OF ERROR MESSAGES ------------------------------------ * Error 0 - E_MEM: Failure to allocate memory. The program aborts immediately. * Error 1 - E_FILEOPEN: Failure to open a file. The program aborts immediately. * Error 2 - E_MEMMANAGER: A memory manager was detected (most commonly - Windows or EMM386). The program aborts as calling in protecetd mode will crash the system. In addition, a known bug in most versions of EMM386 will cause the program to crash in any case. The program aborts immediately. * Error 3 - E_FILEFLUSH: Failure to flush contents of an open file. Execution resumes. * Error 4 - E_FILECLOSE: Failure to close an open file. Execution resumes. * Error 5 - E_NOTPCI: The machine does not support PCI. The program aborts. * Error 6 - E_CARRYFLAG: Carry flag after a PCI_BIOS_PRESENT call was nor cleared, and we therefore assume the machine does not support PCI. An E_NOTPCI ( Error 5 ) signal is raised. * Error 7 - E_RETVAL: PCI_BIOS_PRESENT call returned that PCI support is not present. An E_NOTPCI ( Error 5 ) signal is raised. * Error 8 - E_PCISTRING: PCI_BIOS_PRESENT call did not return in register EDX the string "PCI ". We therefore assume the machine does not support PCI. An E_NOTPCI ( Error 5 ) signal is raised. * Error 9 - E_NODEV: No PCI devices are present, including a host bridge. This means that de-facto there is no PCI support. The program aborts immediately. * Error 10 - E_NO32SUPPORT: No PCI Bios 32-bit enrty point present. If the user specified one of the running modes as 32-bit, the program aborts. * Error 11 - E_NO32STRUCT: The BIOS32 service directory (which makes it possible to fine the PCI Bios-32 entry point) is not present in the memory section where it is supposed to be. The E_NO32SUPPORT ( Error 10 ) flag is raised. * Error 12 - E_CONFLICT32: Conflicting PCI Bios-32 entry point are given by the system. The E_NO32SUPPORT ( Error 10 ) flag is raised. * Error 13 - E_LOCAL32FAIL: The entry point found in the BIOS32 service directory didn't lead to a PCI Bios-32 entry point. Execution resumes, as a successful entry point is searched for. * Error 14 - E_TOOMANYBUS: More busses were found on the system than the number specified by the user (if the user didn't change program parameters, the default is 4). Since most systems lack PCI-PCI Bridges, this error note usually points to the fact that one physical device is mapped to multiple bus/device PCI combinations. * Error 15 - E_TOOMANYDEV: More devices were found on the system than the number specified by the user (if the user didn't change program parameters, the default is 16). Since most systems lack PCI-PCI Bridges, this error note usually points to the fact that one physical device is mapped to multiple bus/device PCI combinations. * Error 16 - E_CONSISTBUS: Accessing the PCI bus directly returned a value for the last bus on the system which is different from what the PCI_BIOS_PRESENT Bios call returned. * Error 17 - E_CONSISTMECH: Inconsistency between direct PCI bus access and PCI_BIOS_PRESENT call regarding the system's hardware mechanism for accessing the configuration space. * Error 18 - E_PURGED: A given physical device seems to have been mapped as several PCI devices. This is revealed when the configuration space of this device is identical to that of other devices. In such a case, all instances of this device besides the first one are purged. The user may set the "Purge" parameter in the "Log & Setup" window to "No". * Error 19 - E_FINDPCIDEVICE: An attempt was made to access a device (from the list of existing devices) using FIND_PCI_DEVICE call and the call failed. The devices' device and vendor id were presented as parameters and the call was expected to output the correct bus/device combination identifying this device. * Error 20 - E_FINDPCICLASSCODE: An attempt was made to access a device (from the list of existing devices) using FIND_PCI_CLASS_CODE call and the call failed. The devices' class code was presented as parameter and the call was expected to output the correct bus/device combination identifying this device. * Error 21 - E_PCIREAD: The first Dword of the devices' configuration space are read using READ_CONFIG_WORD. If they don't match the value read directly from the configuration space, this error message is output. * Error 22 - E_READBFAIL: A READ_CONFIG_BYTE call has failed (Carry flag not cleared). * Error 23 - E_READWFAIL: A READ_CONFIG_WORD call has failed (Carry flag not cleared). * Error 24 - E_READDFAIL: A READ_CONFIG_DWORD call has failed (Carry flag not cleared). * Error 25 - E_DIFFBW: READ_CONFIG_BYTE and READ_CONFIG_WORD return different results. * Error 26 - E_DIFFBD: READ_CONFIG_BYTE and READ_CONFIG_DWORD return different results. * Error 27 - E_DIFFWD: READ_CONFIG_WORD and READ_CONFIG_DWORD return different results. * Error 28 - E_NOSUCHDEV: One of the read calls read the vendor id of a certain device and found that it is different from FFFFh. This indicates an active PCI device, but this device was not found when the configuration space was read directly. * Error 29 - E_CANTRESUME: Due to failure of READ_CONFIG_... the read tets are stopped. * Error 30 - E_BOUNDFIND: Failure of boundry-condition testing of FIND_PCI_DEVICE call: An unexpected return code was returned by the call. * Error 31 - E_BOUNDFINDF: Failure of boundry-condition testing of FIND_PCI_DEVICE call: The carry flag was unexpectedly cleared. * Error 32 - E_BOUNDCLASS: Failure of boundry-condition testing of FIND_PCI_CLASS_CODE call: An unexpected return code was returned by the call. * Error 33 - E_BOUNDCLASSF: Failure of boundry-condition testing of FIND_PCI_CLASS_CODE call: The carry flag was unexpectedly cleared. * Error 34 - E_BOUNDCYC: Failure of boundry-condition testing of GENERATE_SPECIAL_CYCLE call: An unexpected return code was returned by the call. * Error 35 - E_BOUNDCYCF: Failure of boundry-condition testing of GENERATE_SPECIAL_CYCLE call: The carry flag was unexpectedly cleared. * Error 36 - E_BOUNDBYTE: Failure of boundry-condition testing of READ_CONFIG_BYTE call: An unexpected return code was returned by the call. * Error 37 - E_BOUNDBYTEF: Failure of boundry-condition testing of READ_CONFIG_BYTE call: The carry flag was unexpectedly cleared. * Error 38 - E_BOUNDWORD: Failure of boundry-condition testing of READ_CONFIG_WORD call: An unexpected return code was returned by the call. * Error 39 - E_BOUNDWORDF: Failure of boundry-condition testing of READ_CONFIG_WORD call: The carry flag was unexpectedly cleared. * Error 40 - E_BOUNDDOUBLE: Failure of boundry-condition testing of READ_CONFIG_DWORD call: An unexpected return code was returned by the call. * Error 41 - E_BOUNDDOUBLEF: Failure of boundry-condition testing of READ_CONFIG_DWORD call: The carry flag was unexpectedly cleared. * Error 42 - E_INDEXFIND: For a given device, the "index" value of the Bios calls ( = number of such devices in the system) differs from the result obtained by reading the configuration space directly. * Error 43 - E_INDEXFINDT: For a given device, the "index" value of the FIND_PCI_DEVICE Bios call ( = number of such devices in the system) is larger than the total number of devices in the system. * Error 44 - E_INDEXCLASS: For a given device, the "index" value of the the FIND_PCI_CLASS_CODE Bios calls ( = number of such devices in the system) differs from the result obtained by reading the configuration space directly. * Error 45 - E_INDEXCLASST: For a given device, the "index" value of the FIND_PCI_CLASS_CODE Bios call ( = number of such devices in the system) is larger than the total number of devices in the system. * Error 50 - E_REGISTERCORRUPTION: After a Bios call has returned, it was found that registers which should not have been changed were changed. Only registers in which return values are given should change and all the rest should remain as before the call was performed. * Error 51 - E_REGISTERMISMATCH: Bios calls performed in differnt calling modes (RM = Real mode, PM16 = 16-bit protected mode, PM32 = 32-bit protected mode), have returned different results.