[Xen-changelog] This patch adds a section to the documentation on the late binding

[Xen patchbot -unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>]

# HG changeset patch
# User kaf24@xxxxxxxxxxxxxxxxxxxx
# Node ID 14659382edd3e1e51be9fde1cf89e1faf51019a6
# Parent  1dce0d05c763e5b86bdf6d1a1d622b5414a3bc43
This patch adds a section to the documentation on the late binding
feature for PCI devices. It provides some examples (mostly stolen from
the e-mail which accompanied the late-binding patch) of how to use the
sysfs attributes for late binding.

This patch was revised from the last documentation patch that I
submitted which included this and some documentation on the permissive
flag. I've divided the two sections up and I'd like this one considered
for acceptance now while I revise the permissive flag code.

Signed-off-by: Ryan Wilson <hap9@xxxxxxxxxxxxxx>

diff -r 1dce0d05c763 -r 14659382edd3 docs/src/user.tex
--- a/docs/src/user.tex Sat Apr 15 09:16:05 2006
+++ b/docs/src/user.tex Sat Apr 15 10:28:55 2006
@@ -1232,8 +1232,15 @@
 \subsection{PCI}
 \label{ss:pcidd}
 
-Individual PCI devices can be assigned to a given domain to allow that
-domain direct access to the PCI hardware. To use this functionality, ensure
+Individual PCI devices can be assigned to a given domain (a PCI driver domain)
+to allow that domain direct access to the PCI hardware.
+
+While PCI Driver Domains can increase the stability and security of a system
+by addressing a number of security concerns, there are some security issues
+that remain that you can read about in Section~\ref{s:ddsecurity}.
+
+\subsubsection{Compile-Time Setup}
+To use this functionality, ensure
 that the PCI Backend is compiled in to a privileged domain (e.g. domain 0)
 and that the domains which will be assigned PCI devices have the PCI Frontend
 compiled in. In XenLinux, the PCI Backend is available under the Xen
@@ -1241,21 +1248,73 @@
 architecture-specific "Bus Options" section. You may compile both the backend
 and the frontend into the same kernel; they will not affect each other.
 
+\subsubsection{PCI Backend Configuration - Binding at Boot}
 The PCI devices you wish to assign to unprivileged domains must be "hidden"
 from your backend domain (usually domain 0) so that it does not load a driver
 for them. Use the \path{pciback.hide} kernel parameter which is specified on
 the kernel command-line and is configurable through GRUB (see
 Section~\ref{s:configure}). Note that devices are not really hidden from the
-backend domain. The PCI Backend ensures that no other device driver loads
-for those devices. PCI devices are identified by hexadecimal
-slot/funciton numbers (on Linux, use \path{lspci} to determine slot/funciton
-numbers of your devices) and can be specified with or without the PCI domain: 
\\
+backend domain. The PCI Backend appears to the Linux kernel as a regular PCI
+device driver. The PCI Backend ensures that no other device driver loads
+for the devices by binding itself as the device driver for those devices.
+PCI devices are identified by hexadecimal slot/funciton numbers (on Linux,
+use \path{lspci} to determine slot/funciton numbers of your devices) and
+can be specified with or without the PCI domain: \\
 \centerline{  {\tt ({\em bus}:{\em slot}.{\em func})} example {\tt (02:1d.3)}} 
\\
 \centerline{  {\tt ({\em domain}:{\em bus}:{\em slot}.{\em func})} example 
{\tt (0000:02:1d.3)}} \\
 
 An example kernel command-line which hides two PCI devices might be: \\
 \centerline{ {\tt root=/dev/sda4 ro console=tty0 
pciback.hide=(02:01.f)(0000:04:1d.0) } } \\
 
+\subsubsection{PCI Backend Configuration - Late Binding}
+PCI devices can also be bound to the PCI Backend after boot through the manual
+binding/unbinding facilities provided by the Linux kernel in sysfs (allowing
+for a Xen user to give PCI devices to driver domains that were not specified
+on the kernel command-line). There are several attributes with the PCI
+Backend's sysfs directory (\path{/sys/bus/pci/drivers/pciback}) that can be
+used to bind/unbind devices:
+
+\begin{description}
+\item[slots] lists all of the PCI slots that the PCI Backend will try to seize
+  (or "hide" from Domain 0). A PCI slot must appear in this list before it can
+  be bound to the PCI Backend through the \path{bind} attribute.
+\item[new\_slot] write the name of a slot here (in 0000:00:00.0 format) to
+  have the PCI Backend seize the device in this slot.
+\item[remove\_slot] write the name of a slot here (same format as
+  \path{new\_slot}) to have the PCI Backend no longer try to seize devices in
+  this slot. Note that this does not unbind the driver from a device it has
+  already seized.
+\item[bind] write the name of a slot here (in 0000:00:00.0 format) to have
+  the Linux kernel attempt to bind the device in that slot to the PCI Backend
+  driver.
+\item[unbind] write the name of a skit here (same format as \path{bind}) to 
have
+  the Linux kernel unbind the device from the PCI Backend. DO NOT unbind a
+  device while it is currently given to a PCI driver domain!
+\end{description}
+
+Some examples:
+
+Bind a device to the PCI Backend which is not bound to any other driver.
+\begin{verbatim}
+# # Add a new slot to the PCI Backend's list
+# echo -n 0000:01:04.d > /sys/bus/pci/drivers/pciback/new_slot
+# # Now that the backend is watching for the slot, bind to it
+# echo -n 0000:01:04.d > /sys/bus/pci/drivers/pciback/bind
+\end{verbatim}
+
+Unbind a device from its driver and bind to the PCI Backend.
+\begin{verbatim}
+# # Unbind a PCI network card from its network driver
+# echo -n 0000:05:02.0 > /sys/bus/pci/drivers/3c905/unbind
+# # And now bind it to the PCI Backend
+# echo -n 0000:05:02.0 > /sys/bus/pci/drivers/pciback/new_slot
+# echo -n 0000:05:02.0 > /sys/bus/pci/drivers/pciback/bind
+\end{verbatim}
+
+Note that the "-n" option in the example is important as it causes echo to not
+output a new-line.
+
+\subsubsection{PCI Frontend Configuration}
 To configure a domU to receive a PCI device:
 
 \begin{description}
@@ -1281,9 +1340,6 @@
 \end{verbatim}
 }
 \end{description}
-
-There are a number of security concerns associated with PCI Driver Domains
-that you can read about in Section~\ref{s:ddsecurity}.
 
 %% There are two possible types of privileges: IO privileges and
 %% administration privileges.

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog