[PATCH v2] device-types/blk/description.tex: Allow longer device IDs to be returned

["Richard W.M. Jones" <rjones@redhat.com>]

SCSI-based paravirtualized block devices including virtio-scsi and
VMware's pvscsi allow longer device IDs.  This presents an issue when
we change the backing of a disk from one type to another, eg from
pvscsi to virtio-blk, or virtio-scsi to virtio-blk.  The longer device
ID has to be truncated to 20 bytes.  This results in guest visible
changes, notably /dev/disk/by-id/ paths are different, so any
mountpoints or configuration files that use these paths will break.

Therefore extend virtio-blk to allow longer device IDs.  I chose 247
bytes (ASCII chars) as the new limit since SCSI serials can in theory
be this long.  Real serials will be much shorter than this; the aim is
to allow UUIDs to be preserved which would use 32 or 36 ASCII chars.

A new feature bit is introduced to indicate that long device IDs are
supported.

Signed-off-by: Richard W.M. Jones <rjones@redhat.com>
---
 device-types/blk/description.tex | 37 ++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex
index 3b3a4e7..72afcd8 100644
--- a/device-types/blk/description.tex
+++ b/device-types/blk/description.tex
@@ -73,6 +73,9 @@ \subsection{Feature bits}\label{sec:Device Types / Block Device / Feature bits}
     VIRTIO_BLK_REQ_FLAG_OUT_FUA flag in the \field{flags} bitfield of the
     \field{virtio_blk_req} structure for VIRTIO_BLK_T_OUT requests.
 
+\item[VIRTIO_BLK_F_LONG_ID (20)] Device supports long device ID
+    strings via VIRTIO_BLK_T_GET_LONG_ID requests.
+
 \end{description}
 
 \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Block Device / Feature bits / Legacy Interface: Feature bits}
@@ -457,9 +460,9 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 The type of the request is either a read (VIRTIO_BLK_T_IN), a write
 (VIRTIO_BLK_T_OUT), a discard (VIRTIO_BLK_T_DISCARD), a write zeroes
 (VIRTIO_BLK_T_WRITE_ZEROES), a flush (VIRTIO_BLK_T_FLUSH), a get device ID
-string command (VIRTIO_BLK_T_GET_ID), a secure erase
-(VIRTIO_BLK_T_SECURE_ERASE), or a get device lifetime command
-(VIRTIO_BLK_T_GET_LIFETIME).
+string command (VIRTIO_BLK_T_GET_ID or VIRTIO_BLK_T_GET_LONG_ID),
+a secure erase (VIRTIO_BLK_T_SECURE_ERASE), or a get device lifetime
+command (VIRTIO_BLK_T_GET_LIFETIME).
 
 \begin{lstlisting}
 #define VIRTIO_BLK_T_IN           0
@@ -469,7 +472,8 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 #define VIRTIO_BLK_T_GET_LIFETIME 10
 #define VIRTIO_BLK_T_DISCARD      11
 #define VIRTIO_BLK_T_WRITE_ZEROES 13
-#define VIRTIO_BLK_T_SECURE_ERASE   14
+#define VIRTIO_BLK_T_SECURE_ERASE 14
+#define VIRTIO_BLK_T_GET_LONG_ID  32
 \end{lstlisting}
 
 The \field{flags} bitfield is ignored by the device unless
@@ -515,9 +519,25 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 the device to discard the specified range, provided that following reads return
 zeroes.
 
-VIRTIO_BLK_T_GET_ID requests fetch the device ID string from the device into
-\field{data}.  The device ID string is a NUL-padded ASCII string up to 20 bytes
-long.  If the string is 20 bytes long then there is no NUL terminator.
+VIRTIO_BLK_T_GET_ID or VIRTIO_BLK_T_GET_LONG_ID requests fetch the
+device ID string from the device into \field{data}.  The device ID
+string is an ASCII string which can be up to 247 bytes long.
+
+VIRTIO_BLK_T_GET_ID fetches the first 20 bytes of the device ID
+string.  If the ID is shorter than 20 bytes, then the response is
+padded with NUL bytes so its length is 20 bytes.  (Note that if the ID
+is 20 bytes or longer, this means the response will not be NUL
+terminated.)
+
+If the VIRTIO_BLK_F_LONG_ID feature is offered,
+VIRTIO_BLK_T_GET_LONG_ID fetches the complete device ID string.  The
+response is always 248 bytes long, padded to this length with NUL
+bytes.  Since the longest permitted device ID string is 247 bytes, the
+response is NUL terminated.
+
+Although 247 byte device ID strings are supported, there may be
+interoperability problems if strings longer than 128 bytes are used.
+It is also advisable to use only 7 bit ASCII characters.
 
 The \field{data} used for VIRTIO_BLK_T_GET_LIFETIME requests is populated
 by the device, and is of the form
@@ -913,6 +933,9 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 
 The length of \field{data} MUST be 20 bytes for VIRTIO_BLK_T_GET_ID requests.
 
+The length of \field{data} MUST be 248 bytes for VIRTIO_BLK_T_GET_LONG_ID
+requests.
+
 VIRTIO_BLK_T_DISCARD requests MUST NOT contain more than
 \field{max_discard_seg} struct virtio_blk_discard_write_zeroes segments in
 \field{data}.
-- 
2.55.0