From: Paul Durrant <paul@xen.org>
To: xen-devel@lists.xenproject.org
Cc: Paul Durrant <pdurrant@amazon.com>,
Ian Jackson <iwj@xenproject.org>, Wei Liu <wl@xen.org>
Subject: [PATCH v4 16/23] docs/man: fix xl(1) documentation for 'pci' operations
Date: Tue, 24 Nov 2020 08:01:52 +0000 [thread overview]
Message-ID: <20201124080159.11912-17-paul@xen.org> (raw)
In-Reply-To: <20201124080159.11912-1-paul@xen.org>
From: Paul Durrant <pdurrant@amazon.com>
Currently the documentation completely fails to mention the existence of
PCI_SPEC_STRING. This patch tidies things up, specifically clarifying that
'pci-assignable-add/remove' take <BDF> arguments where as 'pci-attach/detach'
take <PCI_SPEC_STRING> arguments (which will be enforced in a subsequent
patch).
Signed-off-by: Paul Durrant <pdurrant@amazon.com>
---
Cc: Ian Jackson <iwj@xenproject.org>
Cc: Wei Liu <wl@xen.org>
---
docs/man/xl.1.pod.in | 28 +++++++++++++++++-----------
1 file changed, 17 insertions(+), 11 deletions(-)
diff --git a/docs/man/xl.1.pod.in b/docs/man/xl.1.pod.in
index f92bacfa72..c5fbce3b5c 100644
--- a/docs/man/xl.1.pod.in
+++ b/docs/man/xl.1.pod.in
@@ -1597,14 +1597,18 @@ List virtual network interfaces for a domain.
=item B<pci-assignable-list>
-List all the assignable PCI devices.
+List all the B<BDF> of assignable PCI devices. See
+L<xl-pci-configuration(5)> for more information.
+
These are devices in the system which are configured to be
available for passthrough and are bound to a suitable PCI
backend driver in domain 0 rather than a real driver.
=item B<pci-assignable-add> I<BDF>
-Make the device at PCI Bus/Device/Function BDF assignable to guests.
+Make the device at B<BDF> assignable to guests. See
+L<xl-pci-configuration(5)> for more information.
+
This will bind the device to the pciback driver and assign it to the
"quarantine domain". If it is already bound to a driver, it will
first be unbound, and the original driver stored so that it can be
@@ -1620,8 +1624,10 @@ being used.
=item B<pci-assignable-remove> [I<-r>] I<BDF>
-Make the device at PCI Bus/Device/Function BDF not assignable to
-guests. This will at least unbind the device from pciback, and
+Make the device at B<BDF> not assignable to guests. See
+L<xl-pci-configuration(5)> for more information.
+
+This will at least unbind the device from pciback, and
re-assign it from the "quarantine domain" back to domain 0. If the -r
option is specified, it will also attempt to re-bind the device to its
original driver, making it usable by Domain 0 again. If the device is
@@ -1637,15 +1643,15 @@ As always, this should only be done if you trust the guest, or are
confident that the particular device you're re-assigning to dom0 will
cancel all in-flight DMA on FLR.
-=item B<pci-attach> I<domain-id> I<BDF>
+=item B<pci-attach> I<domain-id> I<PCI_SPEC_STRING>
-Hot-plug a new pass-through pci device to the specified domain.
-B<BDF> is the PCI Bus/Device/Function of the physical device to pass-through.
+Hot-plug a new pass-through pci device to the specified domain. See
+L<xl-pci-configuration(5)> for more information.
-=item B<pci-detach> [I<OPTIONS>] I<domain-id> I<BDF>
+=item B<pci-detach> [I<OPTIONS>] I<domain-id> I<PCI_SPEC_STRING>
-Hot-unplug a previously assigned pci device from a domain. B<BDF> is the PCI
-Bus/Device/Function of the physical device to be removed from the guest domain.
+Hot-unplug a pci device that was previously passed through to a domain. See
+L<xl-pci-configuration(5)> for more information.
B<OPTIONS>
@@ -1660,7 +1666,7 @@ even without guest domain's collaboration.
=item B<pci-list> I<domain-id>
-List pass-through pci devices for a domain.
+List the B<BDF> of pci devices passed through to a domain.
=back
--
2.11.0
next prev parent reply other threads:[~2020-11-24 8:31 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-24 8:01 [PATCH v4 00/23] xl / libxl: named PCI pass-through devices Paul Durrant
2020-11-24 8:01 ` [PATCH v4 01/23] xl / libxl: s/pcidev/pci and remove DEFINE_DEVICE_TYPE_STRUCT_X Paul Durrant
2020-12-01 12:32 ` Oleksandr Andrushchenko
2020-12-03 13:00 ` Paul Durrant
2020-11-24 8:01 ` [PATCH v4 02/23] libxl: make libxl__device_list() work correctly for LIBXL__DEVICE_KIND_PCI Paul Durrant
2020-12-01 12:50 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 03/23] libxl: Make sure devices added by pci-attach are reflected in the config Paul Durrant
2020-12-01 13:12 ` Oleksandr Andrushchenko
2020-12-03 13:17 ` Paul Durrant
2020-12-03 13:20 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 04/23] libxl: add/recover 'rdm_policy' to/from PCI backend in xenstore Paul Durrant
2020-12-01 13:13 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 05/23] libxl: s/detatched/detached in libxl_pci.c Paul Durrant
2020-12-01 13:15 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 06/23] libxl: remove extraneous arguments to do_pci_remove() " Paul Durrant
2020-12-01 13:41 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 07/23] libxl: stop using aodev->device_config in libxl__device_pci_add() Paul Durrant
2020-12-01 13:42 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 08/23] libxl: generalise 'driver_path' xenstore access functions in libxl_pci.c Paul Durrant
2020-12-01 13:48 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 09/23] libxl: remove unnecessary check from libxl__device_pci_add() Paul Durrant
2020-12-01 13:51 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 10/23] libxl: remove get_all_assigned_devices() from libxl_pci.c Paul Durrant
2020-12-01 14:18 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 11/23] libxl: make sure callers of libxl_device_pci_list() free the list after use Paul Durrant
2020-12-01 15:10 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 12/23] libxl: add libxl_device_pci_assignable_list_free() Paul Durrant
2020-12-01 15:17 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 13/23] libxl: use COMPARE_PCI() macro is_pci_in_array() Paul Durrant
2020-12-01 15:20 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 14/23] docs/man: extract documentation of PCI_SPEC_STRING from the xl.cfg manpage Paul Durrant
2020-12-01 15:25 ` Oleksandr Andrushchenko
2020-11-24 8:01 ` [PATCH v4 15/23] docs/man: improve documentation of PCI_SPEC_STRING Paul Durrant
2020-11-24 8:01 ` Paul Durrant [this message]
2020-11-24 8:01 ` [PATCH v4 17/23] libxl: introduce 'libxl_pci_bdf' in the idl Paul Durrant
2020-11-24 8:01 ` [PATCH v4 18/23] libxlu: introduce xlu_pci_parse_spec_string() Paul Durrant
2020-11-24 8:01 ` [PATCH v4 19/23] libxl: modify libxl_device_pci_assignable_add/remove/list/list_free() Paul Durrant
2020-11-24 8:01 ` [PATCH v4 20/23] docs/man: modify xl(1) in preparation for naming of assignable devices Paul Durrant
2020-11-24 8:01 ` [PATCH v4 21/23] xl / libxl: support " Paul Durrant
2020-11-24 8:01 ` [PATCH v4 22/23] docs/man: modify xl-pci-configuration(5) to add 'name' field to PCI_SPEC_STRING Paul Durrant
2020-11-24 8:01 ` [PATCH v4 23/23] xl / libxl: support 'xl pci-attach/detach' by name Paul Durrant
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201124080159.11912-17-paul@xen.org \
--to=paul@xen.org \
--cc=iwj@xenproject.org \
--cc=pdurrant@amazon.com \
--cc=wl@xen.org \
--cc=xen-devel@lists.xenproject.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).