
PciScan v1.10, add PCI PnP support to Dos
Copyright (c) 1999-2002 Bart Lagerweij. All rights reserved.
This program is free Software; you can redistribute it under the terms of
the NU2 License (see nu2lic.txt or http://www.nu2.nu/license/).

Usage: PCISCAN [options] mapfile1 [mapfile2 ...]

options:   -?      this help information
    -v     verbose mode (use also to see a list of PCI devices)
    -s     return slot number
    -u     return bus number
    -d     return device number
    -x     return duplicate devices
    -b<x>  bypass BIOS -- talk directly to PCI hardware ports using
           access mechanism <x> (1 or 2) (using wrong one can
           reboot/hang!)

mapfile:   A plane text file pciscan uses to find PCI devices (see mapfile
           details below for more info)

Errorlevel returned:     0 - OK (no error)
                       255 - Out of memory
                       254 - No PCI BIOS detected
                       253 - Syntax error in mapfile
                       252 - Putenv() error (could not set environment
                             variable)
                             
The return values are returned in environment variable(s) PCIx, x starts at 0 
and is incremented for each next value.
The SLOTx variable will contain the slot where that card is inserted.

It is good practice to clear the PCIx environment variable(s) before you run 
PCISCAN. If PCISCAN returns with errorlevel 0, and the PCI0 environment 
variable is empty, then you know that PCISCAN didn't find any matching PCI 
devices in the mapfile.

How does PCISCAN work?
First you have to known how PCI devices work. Each PCI device has a vendor
ID and a device ID. Each vendor has it's own vendor ID, for example; vendor
ID 8086 is "Intel" (there first CPU) and each device has one or sometimes
more device ID(s). Through this vendor and device ID you can identify a PCI
device.

PCISCAN scans the PCI busses, and keeps a list of vendor and device ID's in
memory, it then scans the mapfile(s) and if a device in the mapfile is found
it returns the return value specified in the mapfile through environment
variable(s) PCIx.

For example, if 2 matches have been found, PCISCAN could return 2 different
return value's. Variable PCI0="aspi8dos.sys" and PCI1="aspi8u2.sys".
This means you have to check all PCIx environment variables.

The folowing batch file loads up to three different adapters (extend if you
need more):

@echo off
rem Sample batchfile for loading Dos ASPI device drivers (up to 3)
rem batchfile uses 'device.com' for loading them
set pci0=
set pci1=
set pci2=
pciscan scsi.map
if errorlevel 1 goto _err1
if "%pci0%" == "" goto _none
echo Loading %pci0%
device.com %pci0%
if errorlevel 1 goto _err2
rem Check for second adapter
if "%pci1%" == "" goto _end
echo Loading %pci1%
device.com %pci1%
if errorlevel 1 goto _err2
rem Check for third adapter
if "%pci2%" == "" goto _end
echo Loading %pci2%
device.com %pci2%
if errorlevel 1 goto _err2
goto _end
:_none
echo *** PCISCAN did not find any matching PCI device(s)
echo Here's a list of devices in your system, check if your adapter
echo needs to be added to the mapfile.
echo.
pciscan -v
pause
goto _end
:_err1
echo *** PCISCAN returned an error...
pause
goto _end
:_err2
echo *** Error loading device driver...
pause
:_end
rem End of sample batchfile

Using PCI vendor and device ID's is also done by windows 9x. For example 
take any Adaptec PCI bases SCSI adapter, the windows 9x driver from adaptec 
comes with 2 driver files; AIC78XX.MPD and AIC78U2.MPD, and one .INF file. 
The mapfile (.INF) file is used to map the vendor and device ID's to the 
right driver file. Try searching for PCI\VEN in the .INF file, and you 
will find (all) the vendor and device ID's witch are supported by a driver. 
Also a complete description of each device is given.

Let's look at "PCI PnP for Dos" (PCISCAN), the Dos driver from adaptec
comes with (PCI) 2 driver files (just like win9x); ASPI8DOS.SYS and
ASPI8U2.SYS and ... no mapfile, because adaptec does not known "PCI PnP
for Dos" (yet!). So you have to create the mapfile yourself, but the
information needed is easily found in the adaptec's .INF file for windows
9x. Look for lines that contain the "PCI\VEN_" string, the next line is
an example;

  %PCI\VEN_9004&DEV_7078.DeviceDesc%= AIC78XX,PCI\VEN_9004&DEV_7078
  ----------------------------------  ------- ---------------------
     |                                   |      |
     +-The description variable          |      +-Vendor ID is 9004
                                         |        Device ID is 7078
            The win9x driver file to use-+

The description variable is defined elsewhere in the .INF file, for example;

  PCI\VEN_9004&DEV_7078.DeviceDesc="Adaptec AIC-7870 PCI SCSI Controller"

This gives us the information we want to build our mapfile.

Mapfile details:
Lines that begin with a ';' are ignored (comment lines). The next lines,
explaning the mapfile syntax, are comment lines so you can use it as an
header for your mapfile.
;
; Mapfile for PCISCAN "PCI PnP for Dos"
;
; Syntax:
;     ret="string_to_return"
;     ven=<vendorID> ["Vendor description"]
;     dev=<deviceID> ["Device description"]
;
; Example:
;     ret="aspi8dos.sys"
;     ven= 9004 "Adaptec"
;     dev= 7078 "Adaptec AIC-7870 PCI SCSI Controller"
;          7178 "Adaptec AHA-294X/AIC-78XX PCI SCSI Controller"
;          7278 "SCSI Channel on Adaptec AHA-3940/3940W PCI SCSI Controller"
;          7478 "Adaptec AHA-2944 PCI SCSI Controller"
;          7578 "SCSI Channel on Adaptec AHA-3944 PCI SCSI Controller"
;          7678 "Adaptec AIC-7870 based PCI SCSI Controller"
;
; Note! Keywords 'ret', 'ven' and 'dev' must be lowercase !!!
;

The 'ret' and 'ven' entries has to be defined before the 'dev' entries, the
order of the 'ret' and 'ven' does not matter. If you want, you can skip the
'ven' and 'dev' descriptions. For example the mapfile below works just as
good as the one in the header above.

; Not so nice (but it works) looking mapfile
ret="aspi8dos.sys" ven= 9004 dev= 7078 7178 7278 7478 7578 7678

Maybe I'll make an INF2MAP utility to extract the entries from the win9x
.INF file.

DEVICE.COM:
Ok, nice to see what PCI bases SCSI adapters are in my system but I can
only load my ASPI driver from config.sys, using device=aspi8dos.sys. You're
right... but there's another way to load device drivers, using a device
driver load utility. I use "DEVICE.COM", don't know from who, but I got it
from the CDGOD55 diskette. I've seen some bad device driver loaders, but
this one works great. DEVICE.COM's filesize=1608, date 17-09-94, 07:50.

Why do we need "PCI PnP support for Dos"?
Well... end-users don't... they have Windows, but if you are a network
administrator, hardware vendor, or field engineer, than you (might) need
it!

You network administator, could make a bootable Dos diskette, containing
all the Dos network drivers for the PCI based LAN adapters you use in your
company. Put all these adapters in PCISCAN's mapfile and PCISCAN will scan
what card is in the system and you can load the right Dos driver file, to
access the network.

You hardware vendor, could make a bootable Dos diskette, and you could scan if
you're PCI based adapter is in the system and start a firmware update, or
a diagnostics utility.

You field engineer, could have a bootable Dos diskette in your toolcase,
PCISCAN will scan what SCSI PCI based adapter is in your system and you
could automaticaly load the right ASPI manager, and... use SCSITOOL for
testing the SCSI devices, or start GHOST to create a ghost image to/from
tape.

Everyone who uses bootable Dos diskettes, and loads drivers from it, should
use PCISCAN "PCI PnP for Dos", to scan for there PCI devices.

I would like to thank:
- Ralf Brown, who's PCICFG source code, showed me how to scan the PCI bus (you 
  should checkout his PCICFG utility it's great! 
  http://www.pobox.com/~ralf/files.html).
- Martin Moens, for putting me to the idea of creating PCISCAN.
- Martin Borkhuis for comming up with the name "PCISCAN" (I always have 
  trouble of thinking the right name).
- Dimitri Janczak for some new ideas and code.
