
Overview
--------

The new PCI server consists of the following main components

1. a resource manager named 'pci-server'. The code is located in pci/server
2. a linkable library of API's, libpci.so. The code is located in pci/lib
3. a collection of additional modules, some required, some optional. The code
   is located in pci/modules. A hardware dependent module (pci/modules/hw) is
   required. One of these needs to exist for each platform variant. The
   remaining modules are optional however you generally will want to make use
   of them all and so will want to put them on your target
4. two utilities, 'pci-tool' and 'rsrmgr_query'. The code is located in
   pci/utils. The first allows you to view devices and the bus topology. The
   second allows you view the resource database entries for PCI related
   resources, namely available address spaces and interrupt vectors for
   MSI/MSI-X. 

There is usage information for each component. If you make changes, bump the
major or minor version number (search on SO_VERSION) appropriately and update
the usage to describe the changes related to the version bump

The new PCI server architecture makes use of configuration files
(see pci/config_files for templates) and environment variables (see pci/pci.h)
in order to run. You will need to set these up properly to be successful.
Specifically, the variables need to be present in the environment of each
executable which uses the PCI server. With the exception of the HW dependent
module (which is required by all executables), you can choose which modules will
be utilized by each executable. For example, if you only want debug logs for a
driver you're currently working on, make sure that the PCI_DEBUG_MODULE
environment variable of every other executable is unset. If you want to test a
new capability module but don't want other executables to use it (even though
they may support that capability), then you could blacklist the module for every
other executable or you could create a private capability module directory and
set the PCI_COMPAT_MODULE_DIR environment variable to that directory only for
the executable you are testing (remember to symlink the other capability modules
to your private directory).

Because it will take time to move drivers over to the new PCI server API's, a
backward compatibility module has been created to map the old PCI server API's
in libc to the new PCI server API's in libpci. The module is selected for use
by setting the PCI_BKWD_COMPAT_MODULE environment variable (see pci/pci.h).
 
There is additional documentation that was checked into PRzilla (PR 205103).

Building the PCI server libraries, modules and resource manager
---------------------------------------------------------------

1.  Check out the entire services/pci directory tree

2.  Create a staging directory to install to and set your QCONF_OVERRIDE to it

3.  make sure you have the latest sys/syspage.h from product/mainline in your
	staging directory or you will get build errors

4.  cd 'pci'

5.  'make CPULIST=<arch> all|install' or just 'make all|install' if you want
    everything

you will need to 'make all' from the top at least once in order to build the
libraries you will need for the other modules and binaries


Using the new PCI server on your target
---------------------------------------

1. If the PCI server will be started in order to enable the mounting of a root
   filesystem, make sure that all of the required libraries and modules are
   included in the target IFS otherwise, they and the pci-server binary can
   reside on the root filesystem device and be started later

2. make sure that all required environment variables are set to point to the
   location of the library and modules in the build file. Also remember to set
   these same environment variables when you start a new session (like when you
   login)
   
   For example, the following can be added to the build file startup-script
   immediately after the procmgr_symlink line
   
       PCI_HW_MODULE=/lib/dll/pci/pci_hw-Intel_x86.so
       PCI_BKWD_COMPAT_MODULE=/lib/dll/pci/pci_bkwd_compat.so
       PCI_SLOG_MODULE=/lib/dll/pci/pci_slog.so
       PCI_DEBUG_MODULE=/lib/dll/pci/pci_debug.so
       PCI_BASE_VERBOSITY=2
   
3. make sure that /lib/dll/pci (or the location of libpci.so) is included in
   the LD_LIBRARY_PATH environment variable on the procnto line of your build
   file

4. make sure you are using libc from product/mainline

5. check the pci/config_files/ directory to see if there is a HW config file for
   your target (pci_hw-<board>.cfg. If there is, put it on the target and make
   sure that the PCI_HW_CONFIG_FILE environment variable points to it. Currently
   there is such a file for the Crownbay board

6. (x86 diskboot only)
   If booting a BIOS based (ie. a non fastboot) x86 machine, an additional
   binary needs to be replaced, 'diskboot'. The reason for this is because
   diskboot will not propagate the environment established in the build file
   'startup-script' and hence none of the required PCI_* environment variables
   will be set for the programs launched by diskboot. This will need to be fixed
   but in the meantime, pci/tmp/x86 contains an updated 6.5.0_utils_diskboot. It
   can be added to your image by changing the build file line
   
       diskboot
   to
       diskboot=<path to>/pci/tmp/x86/6.5.0_utils_diskboot
       
   Also, the line
       
       pci-bios=pci-bios-v2
   
   must be changed to
       
       pci-bios=<path to>/pci-server

Depending on the verbosity level and whether or not you are using the debug
module, you will probably want to start slogger with a larger buffer

