1.\" $NetBSD: pciback.4,v 1.5 2014/03/18 18:20:39 riastradh Exp $ 2.\" 3.\" Copyright (c) 2011 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jean-Yves Migeon <jym@NetBSD.org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 8, 2011 31.Dt PCIBACK 4 xen 32.Os 33.Sh NAME 34.Nm pciback 35.Nd Xen backend paravirtualized PCI pass-through driver 36.Sh SYNOPSIS 37.Cd "pciback* at pci?" 38.Sh DESCRIPTION 39The 40.Nm 41driver is the backend part of the PCI pass-through functionality 42that can be used by the 43.Tn Xen 44dom0 to export 45.Xr pci 4 46devices to a guest domain. 47To export a PCI device to a guest domain, the device has to be 48attached to 49.Nm 50in the dom0. 51.Pp 52When the guest domain is 53.Nx , 54the device attached to the 55.Nm 56driver will attach to a 57.Xr xpci 4 58bus inside the guest domain. 59.Sh EXAMPLES 60To attach a device to the 61.Nm 62driver, 63follow these steps: 64.Bl -enum -offset indent -compact 65.It 66look for the device PCI ID, via 67.Xr pcictl 8 . 68.It 69edit 70.Xr boot.cfg 5 71and add the PCI ID to the list of PCI IDs that you want to 72attach to 73.Nm , 74in bus:device.function notation. 75The list is passed to dom0 module via the 76.Ic pciback.hide 77parameter: 78.Dl pciback.hide=(bus:dev.fun)(bus:dev.func)(...) 79See also 80.Xr boot 8 . 81.It 82reboot dom0. 83.It 84add the PCI ID to the list of PCI devices in the domain 85configuration file: 86.Dl pci = ['bus:dev.fun', '...'] 87.It 88start the guest domain. 89.El 90.Sh SEE ALSO 91.Xr pci 4 , 92.Xr xpci 4 , 93.Xr boot 8 , 94.Xr pcictl 8 95.Sh HISTORY 96The 97.Nm 98driver first appeared in 99.Nx 5.1 . 100.Sh AUTHORS 101.An -nosplit 102The 103.Nm 104driver was written by 105.An Manuel Bouyer Aq Mt bouyer@NetBSD.org . 106.Sh CAVEATS 107Currently, to attach a device to the 108.Nm 109backend, this procedure has to be performed at 110.Xr boot 8 111time. 112In the future, it will be possible to do it without requiring 113a dom0 reboot. 114.Sh SECURITY CONSIDERATIONS 115As PCI passthrough offers the possibility for guest domains 116to send arbitrary PCI commands to a physical device, this has 117direct impact on the overall stability and security of the system. 118For example, in case of erroneous or malicious commands, the device 119could overwrite physical memory portions, via DMA. 120