changeset 10884:a438506e241d

[PCI] Basic documentation for the per-device permissive
flag and the two policy files. However, the general intent of this
patch set is to avoid the need for user interaction, so documentation
is somewhat sparse.

Signed-off-by: Chris Bookholt <>
author kfraser@localhost.localdomain
date Fri Jul 28 13:00:57 2006 +0100 (2006-07-28)
parents df80de098d15
children 1f7423795115 7c3a27bb291e
files docs/src/user.tex
line diff
     1.1 --- a/docs/src/user.tex	Fri Jul 28 12:59:48 2006 +0100
     1.2 +++ b/docs/src/user.tex	Fri Jul 28 13:00:57 2006 +0100
     1.3 @@ -1287,8 +1287,8 @@ Section~\ref{s:configure}). Note that de
     1.4  backend domain. The PCI Backend appears to the Linux kernel as a regular PCI
     1.5  device driver. The PCI Backend ensures that no other device driver loads
     1.6  for the devices by binding itself as the device driver for those devices.
     1.7 -PCI devices are identified by hexadecimal slot/funciton numbers (on Linux,
     1.8 -use \path{lspci} to determine slot/funciton numbers of your devices) and
     1.9 +PCI devices are identified by hexadecimal slot/function numbers (on Linux,
    1.10 +use \path{lspci} to determine slot/function numbers of your devices) and
    1.11  can be specified with or without the PCI domain: \\
    1.12  \centerline{  {\tt ({\em bus}:{\em slot}.{\em func})} example {\tt (02:1d.3)}} \\
    1.13  \centerline{  {\tt ({\em domain}:{\em bus}:{\em slot}.{\em func})} example {\tt (0000:02:1d.3)}} \\
    1.14 @@ -1344,6 +1344,50 @@ Unbind a device from its driver and bind
    1.15  Note that the "-n" option in the example is important as it causes echo to not
    1.16  output a new-line.
    1.18 +\subsubsection{PCI Backend Configuration - User-space Quirks}
    1.19 +Quirky devices (such as the Broadcom Tigon 3) may need write access to their
    1.20 +configuration space registers.  Xen can be instructed to allow specified PCI
    1.21 +devices write access to specific configuration space registers.  The policy may
    1.22 +be found in:
    1.23 +
    1.24 +\centerline{ \path{/etc/xen/xend-pci-quirks.sxp} }
    1.25 +
    1.26 +The policy file is heavily commented and is intended to provide enough
    1.27 +documentation for developers to extend it.
    1.28 +
    1.29 +\subsubsection{PCI Backend Configuration - Permissive Flag}
    1.30 +If the user-space quirks approach doesn't meet your needs you may want to enable
    1.31 +the permissive flag for that device.  To do so, first get the PCI domain, bus,
    1.32 +slot, and function information from dom0 via \path{lspci}.  Then augment the
    1.33 +user-space policy for permissive devices.  The permissive policy can be found
    1.34 +in:
    1.35 +
    1.36 +\centerline{ \path{/etc/xen/xend-pci-permissive.sxp} }
    1.37 +
    1.38 +Currently, the only way to reset the permissive flag is to unbind the device
    1.39 +from the PCI Backend driver.
    1.40 +
    1.41 +\subsubsection{PCI Backend - Checking Status}
    1.42 +There two important sysfs nodes that provide a mechanism to view specifics on
    1.43 +quirks and permissive devices:
    1.44 +\begin{description}
    1.45 +\item \path{/sys/bus/drivers/pciback/permissive} \\
    1.46 + Use \path{cat} on this file to view a list of permissive slots.
    1.47 +\item \path{/sys/bus/drivers/pciback/quirks} \\
    1.48 + Use \path{cat} on this file view a hierarchical view of devices bound to the
    1.49 +PCI backend, their PCI vendor/device ID, and any quirks that are associated with
    1.50 +that particular slot.  
    1.51 +\end{description}
    1.52 +
    1.53 +You may notice that every device bound to the PCI backend has 17 quirks standard 
    1.54 +"quirks" regardless of \path{xend-pci-quirks.sxp}.  These default entries are
    1.55 +necessary to support interactions between the PCI bus manager and the device bound
    1.56 +to it.  Even non-quirky devices should have these standard entries.  
    1.57 +
    1.58 +In this case, preference was given to accuracy over aesthetics by choosing to
    1.59 +show the standard quirks in the quirks list rather than hide them from the
    1.60 +inquiring user 
    1.61 +
    1.62  \subsubsection{PCI Frontend Configuration}
    1.63  To configure a domU to receive a PCI device: