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

kernel test robot
2022-07-04T21:21:59Z

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