Re: [PATCH v20 18/20] s390/vfio-ap: update docs to include dynamic config support

[kernel test robot <lkp@intel.com>]

Hi Tony,

I love your patch! Perhaps something to improve:

[auto build test WARNING on s390/features]
[also build test WARNING on mst-vhost/linux-next linus/master v5.19-rc5 next-20220704]
[cannot apply to kvms390/next]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]

url:    https://github.com/intel-lab-lkp/linux/commits/Tony-Krowiak/s390-vfio-ap-dynamic-configuration-support/20220621-235654
base:   https://git.kernel.org/pub/scm/linux/kernel/git/s390/linux.git features
reproduce: make htmldocs

If you fix the issue, kindly add following tag where applicable
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

>> Documentation/s390/vfio-ap.rst:684: WARNING: Inline strong start-string without end-string.
>> Documentation/s390/vfio-ap.rst:684: WARNING: Inline emphasis start-string without end-string.
>> Documentation/s390/vfio-ap.rst:943: WARNING: Title underline too short.
>> Documentation/s390/vfio-ap.rst:998: WARNING: Definition list ends without a blank line; unexpected unindent.

vim +684 Documentation/s390/vfio-ap.rst

   538	
   539	1. Install the vfio_ap module on the linux host. The dependency chain for the
   540	   vfio_ap module is:
   541	   * iommu
   542	   * s390
   543	   * zcrypt
   544	   * vfio
   545	   * vfio_mdev
   546	   * vfio_mdev_device
   547	   * KVM
   548	
   549	   To build the vfio_ap module, the kernel build must be configured with the
   550	   following Kconfig elements selected:
   551	   * IOMMU_SUPPORT
   552	   * S390
   553	   * ZCRYPT
   554	   * S390_AP_IOMMU
   555	   * VFIO
   556	   * VFIO_MDEV
   557	   * KVM
   558	
   559	   If using make menuconfig select the following to build the vfio_ap module::
   560	
   561	     -> Device Drivers
   562		-> IOMMU Hardware Support
   563		   select S390 AP IOMMU Support
   564		-> VFIO Non-Privileged userspace driver framework
   565		   -> Mediated device driver frramework
   566		      -> VFIO driver for Mediated devices
   567	     -> I/O subsystem
   568		-> VFIO support for AP devices
   569	
   570	2. Secure the AP queues to be used by the three guests so that the host can not
   571	   access them. To secure them, there are two sysfs files that specify
   572	   bitmasks marking a subset of the APQN range as usable only by the default AP
   573	   queue device drivers. All remaining APQNs are available for use by
   574	   any other device driver. The vfio_ap device driver is currently the only
   575	   non-default device driver. The location of the sysfs files containing the
   576	   masks are::
   577	
   578	     /sys/bus/ap/apmask
   579	     /sys/bus/ap/aqmask
   580	
   581	   The 'apmask' is a 256-bit mask that identifies a set of AP adapter IDs
   582	   (APID). Each bit in the mask, from left to right, corresponds to an APID from
   583	   0-255. If a bit is set, the APID belongs to the subset of APQNs marked as
   584	   available only to the default AP queue device drivers.
   585	
   586	   The 'aqmask' is a 256-bit mask that identifies a set of AP queue indexes
   587	   (APQI). Each bit in the mask, from left to right, corresponds to an APQI from
   588	   0-255. If a bit is set, the APQI belongs to the subset of APQNs marked as
   589	   available only to the default AP queue device drivers.
   590	
   591	   The Cartesian product of the APIDs corresponding to the bits set in the
   592	   apmask and the APQIs corresponding to the bits set in the aqmask comprise
   593	   the subset of APQNs that can be used only by the host default device drivers.
   594	   All other APQNs are available to the non-default device drivers such as the
   595	   vfio_ap driver.
   596	
   597	   Take, for example, the following masks::
   598	
   599	      apmask:
   600	      0x7d00000000000000000000000000000000000000000000000000000000000000
   601	
   602	      aqmask:
   603	      0x8000000000000000000000000000000000000000000000000000000000000000
   604	
   605	   The masks indicate:
   606	
   607	   * Adapters 1, 2, 3, 4, 5, and 7 are available for use by the host default
   608	     device drivers.
   609	
   610	   * Domain 0 is available for use by the host default device drivers
   611	
   612	   * The subset of APQNs available for use only by the default host device
   613	     drivers are:
   614	
   615	     (1,0), (2,0), (3,0), (4.0), (5,0) and (7,0)
   616	
   617	   * All other APQNs are available for use by the non-default device drivers.
   618	
   619	   The APQN of each AP queue device assigned to the linux host is checked by the
   620	   AP bus against the set of APQNs derived from the Cartesian product of APIDs
   621	   and APQIs marked as available to the default AP queue device drivers. If a
   622	   match is detected,  only the default AP queue device drivers will be probed;
   623	   otherwise, the vfio_ap device driver will be probed.
   624	
   625	   By default, the two masks are set to reserve all APQNs for use by the default
   626	   AP queue device drivers. There are two ways the default masks can be changed:
   627	
   628	   1. The sysfs mask files can be edited by echoing a string into the
   629	      respective sysfs mask file in one of two formats:
   630	
   631	      * An absolute hex string starting with 0x - like "0x12345678" - sets
   632		the mask. If the given string is shorter than the mask, it is padded
   633		with 0s on the right; for example, specifying a mask value of 0x41 is
   634		the same as specifying::
   635	
   636		   0x4100000000000000000000000000000000000000000000000000000000000000
   637	
   638		Keep in mind that the mask reads from left to right, so the mask
   639		above identifies device numbers 1 and 7 (01000001).
   640	
   641		If the string is longer than the mask, the operation is terminated with
   642		an error (EINVAL).
   643	
   644	      * Individual bits in the mask can be switched on and off by specifying
   645		each bit number to be switched in a comma separated list. Each bit
   646		number string must be prepended with a ('+') or minus ('-') to indicate
   647		the corresponding bit is to be switched on ('+') or off ('-'). Some
   648		valid values are:
   649	
   650		   - "+0"    switches bit 0 on
   651		   - "-13"   switches bit 13 off
   652		   - "+0x41" switches bit 65 on
   653		   - "-0xff" switches bit 255 off
   654	
   655		The following example:
   656	
   657		      +0,-6,+0x47,-0xf0
   658	
   659		Switches bits 0 and 71 (0x47) on
   660	
   661		Switches bits 6 and 240 (0xf0) off
   662	
   663		Note that the bits not specified in the list remain as they were before
   664		the operation.
   665	
   666	   2. The masks can also be changed at boot time via parameters on the kernel
   667	      command line like this:
   668	
   669		 ap.apmask=0xffff ap.aqmask=0x40
   670	
   671		 This would create the following masks::
   672	
   673		    apmask:
   674		    0xffff000000000000000000000000000000000000000000000000000000000000
   675	
   676		    aqmask:
   677		    0x4000000000000000000000000000000000000000000000000000000000000000
   678	
   679		 Resulting in these two pools::
   680	
   681		    default drivers pool:    adapter 0-15, domain 1
   682		    alternate drivers pool:  adapter 16-255, domains 0, 2-255
   683	
 > 684	   Note ***:
   685	   Changing a mask such that one or more APQNs will be taken from a vfio_ap
   686	   mediated device (see below) will fail with an error (EBUSY). A message
   687	   is logged to the kernel ring buffer which can be viewed with the 'dmesg'
   688	   command. The output identifies each APQN flagged as 'in use' and identifies
   689	   the vfio_ap mediated device to which it is assigned; for example:
   690	
   691	   Userspace may not re-assign queue 05.0054 already assigned to 62177883-f1bb-47f0-914d-32a22e3a8804
   692	   Userspace may not re-assign queue 04.0054 already assigned to cef03c3c-903d-4ecc-9a83-40694cb8aee4
   693	

-- 
0-DAY CI Kernel Test Service
https://01.org/lkp