[Libguestfs] [PATCH 1/3] lib: Remove internal details of device name translation from API docs.

[Richard W.M. Jones]

Remove much of the text detailing how device name translation
happened.  Since we removed support for virtio-blk
(commit 9e0294f88fbb30f592396894c9633041b7b89aaf) and deprecated the
‘iface’ parameter, only /dev/sdX device names should be visible
through the public APIs, both in parameters and in return values from
calls like guestfs_list_devices and guestfs_list_partitions.

Note the above is in fact not true for the UML backend, but UML is
broken in the kernel and in any case this will be fixed later.
---
 daemon/guestfsd.c |   3 +-
 lib/guestfs.pod   | 113 +++++-------------------------------------------------
 2 files changed, 11 insertions(+), 105 deletions(-)

diff --git a/daemon/guestfsd.c b/daemon/guestfsd.c
index 1a2350a42..8e9fa9d63 100644
--- a/daemon/guestfsd.c
+++ b/daemon/guestfsd.c
@@ -948,8 +948,7 @@ print_arginfo (const struct printf_info *info, size_t n, int *argtypes)
 #endif
 
 /**
- * Perform device name translation.  See L<guestfs(3)> for the
- * algorithm.  Usually you should not call this directly.
+ * Perform device name translation.
  *
  * It returns a newly allocated string which the caller must free.
  *
diff --git a/lib/guestfs.pod b/lib/guestfs.pod
index 544ca2a3c..f2a54a1fd 100644
--- a/lib/guestfs.pod
+++ b/lib/guestfs.pod
@@ -1697,37 +1697,13 @@ developer to program in confidence against the libguestfs API.
 
 =head2 BLOCK DEVICE NAMING
 
-In the kernel there is now quite a profusion of schemata for naming
-block devices (in this context, by I<block device> I mean a physical
-or virtual hard drive).  The original Linux IDE driver used names
-starting with F</dev/hd*>.  SCSI devices have historically used a
-different naming scheme, F</dev/sd*>.  When the Linux kernel I<libata>
-driver became a popular replacement for the old IDE driver
-(particularly for SATA devices) those devices also used the
-F</dev/sd*> scheme.  Additionally we now have virtual machines with
-paravirtualized drivers.  This has created several different naming
-systems, such as F</dev/vd*> for virtio disks and F</dev/xvd*> for Xen
-PV disks.
-
-As discussed above, libguestfs uses a qemu appliance running an
-embedded Linux kernel to access block devices.  We can run a variety
-of appliances based on a variety of Linux kernels.
-
-This causes a problem for libguestfs because many API calls use device
-or partition names.  Working scripts and the recipe (example) scripts
-that we make available over the internet could fail if the naming
-scheme changes.
-
-Therefore libguestfs defines F</dev/sd*> as the I<standard naming
-scheme>.  Internally F</dev/sd*> names are translated, if necessary,
-to other names as required.  For example, under RHEL 5 which uses the
-F</dev/hd*> scheme, any device parameter F</dev/sda2> is translated to
-F</dev/hda2> transparently.
-
-Note that this I<only> applies to parameters.  The
-L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
-return the true names of the devices and partitions as known to the
-appliance, but see L</guestfs_canonical_device_name>.
+Libguestfs defines F</dev/sd*> as the I<standard naming scheme> for
+devices passed to API calls.  So F</dev/sda> means "the first device
+added by L</guestfs_add_drive_opts>", and F</dev/sdb3> means "the
+third partition on the second device".
+
+Internally device names are sometimes translated, but this should not
+be visible at the API level.
 
 =head3 DISK LABELS
 
@@ -1745,78 +1721,9 @@ Partitions on the disk can be addressed using
 F</dev/disk/guestfs/I<label>I<partnum>>.
 
 Listing devices (L</guestfs_list_devices>) and partitions
-(L</guestfs_list_partitions>) returns the raw block device name.
-However you can use L</guestfs_list_disk_labels> to map disk labels
-to raw block device and partition names.
-
-=head3 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
-
-Usually this translation is transparent.  However in some (very rare)
-cases you may need to know the exact algorithm.  Such cases include
-where you use L</guestfs_config> to add a mixture of virtio and IDE
-devices to the qemu-based appliance, so have a mixture of F</dev/sd*>
-and F</dev/vd*> devices.
-
-The algorithm is applied only to I<parameters> which are known to be
-either device or partition names.  Return values from functions such
-as L</guestfs_list_devices> are never changed.
-
-=over 4
-
-=item *
-
-Is the string a parameter which is a device or partition name?
-
-=item *
-
-Does the string begin with F</dev/sd>?
-
-=item *
-
-Does the named device exist?  If so, we use that device.
-However if I<not> then we continue with this algorithm.
-
-=item *
-
-Replace initial F</dev/sd> string with F</dev/hd>.
-
-For example, change F</dev/sda2> to F</dev/hda2>.
-
-If that named device exists, use it.  If not, continue.
-
-=item *
-
-Replace initial F</dev/sd> string with F</dev/vd>.
-
-If that named device exists, use it.  If not, return an error.
-
-=back
-
-=head3 PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING
-
-Although the standard naming scheme and automatic translation is
-useful for simple programs and guestfish scripts, for larger programs
-it is best not to rely on this mechanism.
-
-Where possible for maximum future portability programs using
-libguestfs should use these future-proof techniques:
-
-=over 4
-
-=item *
-
-Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
-actual device names, and then use those names directly.
-
-Since those device names exist by definition, they will never be
-translated.
-
-=item *
-
-Use higher level ways to identify filesystems, such as LVM names,
-UUIDs and filesystem labels.
-
-=back
+(L</guestfs_list_partitions>) returns the block device names.  However
+you can use L</guestfs_list_disk_labels> to map disk labels to block
+device and partition names.
 
 =head2 NULL DISKS
 
-- 
2.12.0