Lines Matching +full:non +full:- +full:secure +full:- +full:domain
13 The AP adapter cards are exposed via the AP bus. The motivation for vfio-ap
45 sub-directory::
50 * AP domain
53 depending upon the adapter type and hardware configuration. A domain is
54 identified by a number from 0 to 255; however, the maximum domain number is
55 determined by machine model and/or adapter type.. A domain can be thought of
57 domain can be configured with a secure private key used for clear key
58 encryption. A domain is classified in one of two ways depending upon how it
65 usage domain; for example, to set the secure private key for the control
66 domain.
71 domains assigned to the LPAR. The domain number of each usage domain and
73 (see AP Queue section below). The domain number of each control domain will be
76 significant bit, correspond to domains 0-255.
80 An AP queue is the means by which an AP command is sent to a usage domain
83 APQI corresponds to a given usage domain number within the adapter. This tuple
89 the cross product of the AP adapter and usage domain numbers detected when the
111 * NQAP: to enqueue an AP command-request message to a queue
112 * DQAP: to dequeue an AP command-reply message from a queue
115 AP instructions identify the domain that is targeted to process the AP
117 domain that is not one of the usage domains, but the modified domain
132 an APID from 0-255. If a bit is set, the corresponding adapter is valid for
137 corresponds to an AP queue index (APQI) from 0-255. If a bit is set, the
140 * The AP Domain Mask field is a bit mask that identifies the AP control domains
142 changed by an AP command-request message sent to a usage domain from the
143 guest. Each bit in the mask, from left to right, corresponds to a domain from
144 0-255. If a bit is set, the corresponding domain can be modified by an AP
145 command-request message sent to a usage domain.
148 an APQN to identify the AP queue to which an AP command-request message is to be
149 sent (NQAP and PQAP instructions), or from which a command-reply message is to
156 The APQNs can provide secure key functionality - i.e., a private key is stored
157 on the adapter card for each of its domains - so each APQN must be assigned to
161 ------------------------------
163 Guest2: adapter 1,2 domain 7
170 ------------------------------
179 --------------------------------
192 3. VFIO AP mediated pass-through device
195 -------------------------
198 1. Provides the interfaces to secure APQNs for exclusive use of KVM guests.
209 ---------------------------------------------
213 +------------------+
215 +--------------------> cex4queue driver |
217 | +------------------+
220 | +------------------+ +----------------+
222 | +----------------> Device core +----------> matrix device |
224 | | +--------^---------+ +----------------+
226 | | +-------------------+
227 | | +-----------------------------------+ |
230 +--------+---+-v---+ +--------+-------+-+
232 | ap_bus +--------------------- > vfio_ap driver |
234 +--------^---------+ +--^--^------------+
236 apmask | +-----------------------------+ | 11 mdev create
238 +--------+-----+---+ +----------------+-+ +----------------+
240 | admin | | VFIO device core |---------> matrix |
242 +------+-+---------+ +--------^---------+ +--------^-------+
244 | | 9 create vfio_ap-passthrough | |
245 | +------------------------------+ |
246 +-------------------------------------------------------------+
247 12 assign adapter/domain/control domain
252 2. The vfio-ap driver during its initialization will register a single 'matrix'
276 ------------------------------------------
286 The following high-level block diagram shows the main components and interfaces
289 +-------------+
291 | +---------+ | mdev_register_driver() +--------------+
292 | | Mdev | +<-----------------------+ |
294 | | driver | +----------------------->+ |<-> VFIO user
295 | +---------+ | probe()/remove() +--------------+ APIs
300 | +---------+ | mdev_register_parent() +--------------+
301 | |Physical | +<-----------------------+ |
302 | | device | | | vfio_ap.ko |<-> matrix
303 | |interface| +----------------------->+ | device
304 | +---------+ | callback +--------------+
305 +-------------+
315 The VFIO mediated device framework supports creation of user-defined
320 'mdev_supported_types' sub-directory of the device being registered. Along
327 /sys/devices/vfio_ap/matrix/mdev_supported_types/vfio_ap-passthrough
329 Only the read-only attributes required by the VFIO mdev framework will
349 This attribute group identifies the user-defined sysfs attributes of the
356 Write-only attributes for assigning/unassigning an AP adapter to/from the
360 Write-only attributes for assigning/unassigning an AP usage domain to/from
361 the vfio_ap mediated device. To assign/unassign a domain, the domain
362 number of the usage domain is echoed into the respective attribute
365 A read-only file for displaying the APQNs derived from the Cartesian
366 product of the adapter and domain numbers assigned to the vfio_ap mediated
369 A read-only file for displaying the APQNs derived from the Cartesian
370 product of the adapter and domain numbers assigned to the APM and AQM
376 Write-only attributes for assigning/unassigning an AP control domain
377 to/from the vfio_ap mediated device. To assign/unassign a control domain,
378 the ID of the domain to be assigned/unassigned is echoed into the
381 A read-only file for displaying the control domain numbers assigned to the
388 made to the vfio-ap mediated device.
401 Where NN..NN is 64 hexadecimal characters representing a 256-bit value.
402 The leftmost (highest order) bit represents adapter/domain 0.
407 Setting an adapter or domain number greater than the maximum allowed for
451 ----------------------------------
461 * Setting the bits in the ADM corresponding to the domain dIDs assigned to the
465 is not bound to the device driver facilitating its pass-through. Consequently,
474 * The APIDs of the adapters, the APQIs of the domains and the domain numbers of
485 -----------------------------
512 /usr/bin/qemu-system-s390x ... -cpu z13,ap=on,apqci=on,apft=on,apqi=on
517 /usr/bin/qemu-system-s390x ... -cpu host,ap=off,apqci=off,apft=off,apqi=off
521 register for type 10 and newer AP devices - i.e., the cex4card and cex4queue
522 device drivers - need the APFT facility to ascertain the facilities installed on
524 adapter or domain devices will get created by the AP bus running on the
535 ------
537 CARD.DOMAIN TYPE MODE
539 05 CEX5C CCA-Coproc
540 05.0004 CEX5C CCA-Coproc
541 05.00ab CEX5C CCA-Coproc
548 ------
550 CARD.DOMAIN TYPE MODE
552 05 CEX5C CCA-Coproc
553 05.0047 CEX5C CCA-Coproc
554 05.00ff CEX5C CCA-Coproc
558 ------
560 CARD.DOMAIN TYPE MODE
589 -> Device Drivers
590 -> IOMMU Hardware Support
592 -> VFIO Non-Privileged userspace driver framework
593 -> Mediated device driver frramework
594 -> VFIO driver for Mediated devices
595 -> I/O subsystem
596 -> VFIO support for AP devices
598 2. Secure the AP queues to be used by the three guests so that the host can not
599 access them. To secure them, there are two sysfs files that specify
603 non-default device driver. The location of the sysfs files containing the
609 The 'apmask' is a 256-bit mask that identifies a set of AP adapter IDs
611 0-255. If a bit is set, the APID belongs to the subset of APQNs marked as
614 The 'aqmask' is a 256-bit mask that identifies a set of AP queue indexes
616 0-255. If a bit is set, the APQI belongs to the subset of APQNs marked as
622 All other APQNs are available to the non-default device drivers such as the
638 * Domain 0 is available for use by the host default device drivers
645 * All other APQNs are available for use by the non-default device drivers.
659 * An absolute hex string starting with 0x - like "0x12345678" - sets
674 number string must be prepended with a ('+') or minus ('-') to indicate
675 the corresponding bit is to be switched on ('+') or off ('-'). Some
678 - "+0" switches bit 0 on
679 - "-13" switches bit 13 off
680 - "+0x41" switches bit 65 on
681 - "-0xff" switches bit 255 off
685 +0,-6,+0x47,-0xf0
709 default drivers pool: adapter 0-15, domain 1
710 alternate drivers pool: adapter 16-255, domains 0, 2-255
719 … Userspace may not re-assign queue 05.0054 already assigned to 62177883-f1bb-47f0-914d-32a22e3a8804
720 … Userspace may not re-assign queue 04.0054 already assigned to cef03c3c-903d-4ecc-9a83-40694cb8aee4
723 ----------------------------------
724 To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004, 06.0047,
729 echo -5,-6 > /sys/bus/ap/apmask
731 echo -4,-0x47,-0xab,-0xff > /sys/bus/ap/aqmask
764 The administrator, therefore, must take care to secure only AP queues that
779 --- [mdev_supported_types]
780 ------ [vfio_ap-passthrough] (passthrough vfio_ap mediated device type)
781 --------- create
782 --------- [devices]
801 --- [mdev_supported_types]
802 ------ [vfio_ap-passthrough]
803 --------- [devices]
804 ------------ [$uuid1]
805 --------------- assign_adapter
806 --------------- assign_control_domain
807 --------------- assign_domain
808 --------------- matrix
809 --------------- unassign_adapter
810 --------------- unassign_control_domain
811 --------------- unassign_domain
813 ------------ [$uuid2]
814 --------------- assign_adapter
815 --------------- assign_control_domain
816 --------------- assign_domain
817 --------------- matrix
818 --------------- unassign_adapter
819 ----------------unassign_control_domain
820 ----------------unassign_domain
822 ------------ [$uuid3]
823 --------------- assign_adapter
824 --------------- assign_control_domain
825 --------------- assign_domain
826 --------------- matrix
827 --------------- unassign_adapter
828 ----------------unassign_control_domain
829 ----------------unassign_domain
847 If a mistake is made configuring an adapter, domain or control domain,
848 you can use the unassign_xxx files to unassign the adapter, domain or
849 control domain.
884 - Must only be available to the vfio_ap device driver as specified in the
889 - Must NOT be assigned to another vfio_ap mediated device. If even one APQN
893 - Must NOT be assigned while the sysfs /sys/bus/ap/apmask and
897 In order to successfully assign a domain:
899 * The domain number specified must represent a value from 0 up to the
900 maximum domain number configured for the system. If a domain number
904 Note: The maximum domain number can be obtained via the sysfs
907 * Each APQN derived from the Cartesian product of the APQI of the domain
910 - Must only be available to the vfio_ap device driver as specified in the
915 - Must NOT be assigned to another vfio_ap mediated device. If even one APQN
919 - Must NOT be assigned while the sysfs /sys/bus/ap/apmask and
923 In order to successfully assign a control domain:
925 * The domain number specified must represent a value from 0 up to the maximum
926 domain number configured for the system. If a control domain number higher
932 /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on,apqi=on \
933 -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
937 /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on,apqi=on \
938 -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
942 /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on,apqi=on \
943 -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
950 --- [mdev_supported_types]
951 ------ [vfio_ap-passthrough]
952 --------- [devices]
953 ------------ [$uuid1]
954 --------------- remove
972 An adapter, domain or control domain may be hot plugged into a running KVM
976 * The adapter, domain or control domain must also be assigned to the host's
983 * To hot plug a domain, each APQN derived from the Cartesian product
984 comprised of the APQI of the domain being assigned and the APIDs of the
988 An adapter, domain or control domain may be hot unplugged from a running KVM
992 Over-provisioning of AP queues for a KVM guest:
994 Over-provisioning is defined herein as the assignment of adapters or domains to
996 configuration. The idea here is that when the adapter or domain becomes
997 available, it will be automatically hot-plugged into the KVM guest using
1019 ---------------+---------------------------------------------------------------+
1025 +--------------+---------------------------------------------------------------+
1028 +------------+-----------------------------------------------------------------+
1029 | ap_config | ap_config interface for one-shot modifications to mdev config |
1030 +--------------+---------------------------------------------------------------+
1044 virsh detach-device <guestname> <path-to-device-xml>
1046 For example, to hot unplug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 from
1047 the guest named 'my-guest':
1049 virsh detach-device my-guest ~/config/my-guest-hostdev.xml
1051 The contents of my-guest-hostdev.xml:
1053 .. code-block:: xml
1055 <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'>
1057 <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/>
1062 virsh qemu-monitor-command <guest-name> --hmp "device-del <device-id>"
1065 qemu command line with 'id=hostdev0' from the guest named 'my-guest':
1067 .. code-block:: sh
1069 virsh qemu-monitor-command my-guest --hmp "device_del hostdev0"
1074 (QEMU) device-del id=<device-id>
1079 (QEMU) device-del id=hostdev0
1088 virsh attach-device <guestname> <path-to-device-xml>
1090 For example, to hot plug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 into
1091 the guest named 'my-guest':
1093 virsh attach-device my-guest ~/config/my-guest-hostdev.xml
1095 The contents of my-guest-hostdev.xml:
1097 .. code-block:: xml
1099 <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'>
1101 <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/>
1106 virsh qemu-monitor-command <guest-name> --hmp \
1107 "device_add vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>"
1110 62177883-f1bb-47f0-914d-32a22e3a8804 into the guest named 'my-guest' with
1111 device-id hostdev0:
1113 virsh qemu-monitor-command my-guest --hmp \
1114 "device_add vfio-ap,\
1115 sysfsdev=/sys/devices/vfio_ap/matrix/62177883-f1bb-47f0-914d-32a22e3a8804,\
1121 (qemu) device_add "vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>"
1124 62177883-f1bb-47f0-914d-32a22e3a8804 into the guest with the device-id
1127 (QEMU) device-add "vfio-ap,\
1128 sysfsdev=/sys/devices/vfio_ap/matrix/62177883-f1bb-47f0-914d-32a22e3a8804,\