Re: [PATCH v4 7/7] s390: vfio-ap: update documentation
On 6/17/19 7:42 AM, Harald Freudenberger wrote: On 13.06.19 21:39, Tony Krowiak wrote: This patch updates the vfio-ap documentation to include the information below. Changes made to the mdev matrix assignment interfaces: * Allow assignment of APQNs that are not bound to the vfio-ap device driver as long as they are not owned by a zcrypt driver as identified in the AP bus sysfs apmask and aqmask interfaces. * Allow assignment of an AP resource to a mediated device which is in use by a guest to hot plug an adapter, domain and control domain into a running guest. * Allow unassignment of an AP resource from a mediated device which is in use by a guest to hot unplug an adapter, domain and control domain from a running guest. This patch also: * Clarifies the section on configuring the AP bus's apmask and aqmask. * Adds sections on dynamic configuration using the SE or SCLP command. Signed-off-by: Tony Krowiak --- Documentation/s390/vfio-ap.txt | 292 ++--- 1 file changed, 213 insertions(+), 79 deletions(-) diff --git a/Documentation/s390/vfio-ap.txt b/Documentation/s390/vfio-ap.txt index 65167cfe4485..9372a6570ce1 100644 --- a/Documentation/s390/vfio-ap.txt +++ b/Documentation/s390/vfio-ap.txt @@ -81,10 +81,19 @@ definitions: which the AP command is to be sent for processing. The AP bus will create a sysfs device for each APQN that can be derived from - the cross product of the AP adapter and usage domain numbers detected when the - AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and usage - domains 6 and 71 (0x47) are assigned to the LPAR, the AP bus will create the - following sysfs entries: + the Cartesian product of the AP adapter and usage domain numbers detected when + the AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and + usage domains 6 and 71 (0x47) are assigned to the LPAR, the Cartesian product + would be defined by the following table: + + 06 71 + +---+---+ + 04 | (04,06) | (04,47) | + +---|---+ + 10 | (0a,06) | (0a,47) | + +---|---+ + These ascii pictures are nice and show very lovely how this works ... but you use the domain id as column (x) and the adapter id as row (y). Then the APQNs are shown in (y,x) writing then following the scheme (card,domain). I'll fix this. + The AP bus will create the following sysfs entries: /sys/devices/ap/card04/04.0006 /sys/devices/ap/card04/04.0047 @@ -146,10 +155,20 @@ If you recall from the description of an AP Queue, AP instructions include an APQN to identify the AP queue to which an AP command-request message is to be sent (NQAP and PQAP instructions), or from which a command-reply message is to be received (DQAP instruction). The validity of an APQN is defined by the matrix -calculated from the APM and AQM; it is the cross product of all assigned adapter -numbers (APM) with all assigned queue indexes (AQM). For example, if adapters 1 -and 2 and usage domains 5 and 6 are assigned to a guest, the APQNs (1,5), (1,6), -(2,5) and (2,6) will be valid for the guest. +calculated from the APM and AQM; it is the Cartesian product of all assigned +adapter numbers (APM) with all assigned queue indexes (AQM). For example, if +adapters 1 and 2 and usage domains 5 and 6 are assigned to a guest: + + + 05 06 + +---+---+ + 01 | (01,05) | (01,06) | + +---|---+ + 02 | (02,05) | (02,06) | + +---|---+ + + +APQNs (01,05), (01,06), (02,05) and (02,06) will be valid for the guest. The APQNs can provide secure key functionality - i.e., a private key is stored on the adapter card for each of its domains - so each APQN must be assigned to @@ -349,8 +368,9 @@ matrix device. number of the the usage domain is echoed to the respective attribute file. * matrix: - A read-only file for displaying the APQNs derived from the cross product - of the adapter and domain numbers assigned to the mediated matrix device. + A read-only file for displaying the APQNs derived from the Caresian + product of the adapter and domain numbers assigned to the mediated matrix + device. * assign_control_domain: * unassign_control_domain: Write-only attributes for assigning/unassigning an AP control domain @@ -438,9 +458,10 @@ guest use. Example: === Let's now provide an example to illustrate how KVM guests may be given -access to AP facilities. For this example, we will show how to configure -three guests such that executing the lszcrypt command on the guests would -look like this: +access to AP facilities. For this example, we will assume
Re: [PATCH v4 7/7] s390: vfio-ap: update documentation
On 13.06.19 21:39, Tony Krowiak wrote: > This patch updates the vfio-ap documentation to include the information > below. > > Changes made to the mdev matrix assignment interfaces: > > * Allow assignment of APQNs that are not bound to the vfio-ap device > driver as long as they are not owned by a zcrypt driver as identified > in the AP bus sysfs apmask and aqmask interfaces. > > * Allow assignment of an AP resource to a mediated device which is in use > by a guest to hot plug an adapter, domain and control domain into a > running guest. > > * Allow unassignment of an AP resource from a mediated device which is in > use by a guest to hot unplug an adapter, domain and control domain from > a running guest. > > This patch also: > > * Clarifies the section on configuring the AP bus's apmask and aqmask. > > * Adds sections on dynamic configuration using the SE or SCLP command. > > Signed-off-by: Tony Krowiak > --- > Documentation/s390/vfio-ap.txt | 292 > ++--- > 1 file changed, 213 insertions(+), 79 deletions(-) > > diff --git a/Documentation/s390/vfio-ap.txt b/Documentation/s390/vfio-ap.txt > index 65167cfe4485..9372a6570ce1 100644 > --- a/Documentation/s390/vfio-ap.txt > +++ b/Documentation/s390/vfio-ap.txt > @@ -81,10 +81,19 @@ definitions: >which the AP command is to be sent for processing. > >The AP bus will create a sysfs device for each APQN that can be derived > from > - the cross product of the AP adapter and usage domain numbers detected when > the > - AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and usage > - domains 6 and 71 (0x47) are assigned to the LPAR, the AP bus will create > the > - following sysfs entries: > + the Cartesian product of the AP adapter and usage domain numbers detected > when > + the AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and > + usage domains 6 and 71 (0x47) are assigned to the LPAR, the Cartesian > product > + would be defined by the following table: > + > + 06 71 > ++---+---+ > + 04 | (04,06) | (04,47) | > ++---|---+ > + 10 | (0a,06) | (0a,47) | > ++---|---+ > + These ascii pictures are nice and show very lovely how this works ... but you use the domain id as column (x) and the adapter id as row (y). Then the APQNs are shown in (y,x) writing then following the scheme (card,domain). > + The AP bus will create the following sysfs entries: > > /sys/devices/ap/card04/04.0006 > /sys/devices/ap/card04/04.0047 > @@ -146,10 +155,20 @@ If you recall from the description of an AP Queue, AP > instructions include > an APQN to identify the AP queue to which an AP command-request message is > to be > sent (NQAP and PQAP instructions), or from which a command-reply message is > to > be received (DQAP instruction). The validity of an APQN is defined by the > matrix > -calculated from the APM and AQM; it is the cross product of all assigned > adapter > -numbers (APM) with all assigned queue indexes (AQM). For example, if > adapters 1 > -and 2 and usage domains 5 and 6 are assigned to a guest, the APQNs (1,5), > (1,6), > -(2,5) and (2,6) will be valid for the guest. > +calculated from the APM and AQM; it is the Cartesian product of all assigned > +adapter numbers (APM) with all assigned queue indexes (AQM). For example, if > +adapters 1 and 2 and usage domains 5 and 6 are assigned to a guest: > + > + > + 05 06 > ++---+---+ > + 01 | (01,05) | (01,06) | > ++---|---+ > + 02 | (02,05) | (02,06) | > ++---|---+ > + > + > +APQNs (01,05), (01,06), (02,05) and (02,06) will be valid for the guest. > > The APQNs can provide secure key functionality - i.e., a private key is > stored > on the adapter card for each of its domains - so each APQN must be assigned > to > @@ -349,8 +368,9 @@ matrix device. >number of the the usage domain is echoed to the respective attribute >file. > * matrix: > - A read-only file for displaying the APQNs derived from the cross > product > - of the adapter and domain numbers assigned to the mediated matrix > device. > + A read-only file for displaying the APQNs derived from the Caresian > + product of the adapter and domain numbers assigned to the mediated > matrix > + device. > * assign_control_domain: > * unassign_control_domain: >Write-only attributes for assigning/unassigning an AP control domain > @@ -438,9 +458,10 @@ guest use. > Example: > === > Let's now provide an example to illustrate how KVM guests may be given > -access to AP facilities. For this example, we will show how to configure > -three guests such that executing the
[PATCH v4 7/7] s390: vfio-ap: update documentation
This patch updates the vfio-ap documentation to include the information below. Changes made to the mdev matrix assignment interfaces: * Allow assignment of APQNs that are not bound to the vfio-ap device driver as long as they are not owned by a zcrypt driver as identified in the AP bus sysfs apmask and aqmask interfaces. * Allow assignment of an AP resource to a mediated device which is in use by a guest to hot plug an adapter, domain and control domain into a running guest. * Allow unassignment of an AP resource from a mediated device which is in use by a guest to hot unplug an adapter, domain and control domain from a running guest. This patch also: * Clarifies the section on configuring the AP bus's apmask and aqmask. * Adds sections on dynamic configuration using the SE or SCLP command. Signed-off-by: Tony Krowiak --- Documentation/s390/vfio-ap.txt | 292 ++--- 1 file changed, 213 insertions(+), 79 deletions(-) diff --git a/Documentation/s390/vfio-ap.txt b/Documentation/s390/vfio-ap.txt index 65167cfe4485..9372a6570ce1 100644 --- a/Documentation/s390/vfio-ap.txt +++ b/Documentation/s390/vfio-ap.txt @@ -81,10 +81,19 @@ definitions: which the AP command is to be sent for processing. The AP bus will create a sysfs device for each APQN that can be derived from - the cross product of the AP adapter and usage domain numbers detected when the - AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and usage - domains 6 and 71 (0x47) are assigned to the LPAR, the AP bus will create the - following sysfs entries: + the Cartesian product of the AP adapter and usage domain numbers detected when + the AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and + usage domains 6 and 71 (0x47) are assigned to the LPAR, the Cartesian product + would be defined by the following table: + + 06 71 + +---+---+ + 04 | (04,06) | (04,47) | + +---|---+ + 10 | (0a,06) | (0a,47) | + +---|---+ + + The AP bus will create the following sysfs entries: /sys/devices/ap/card04/04.0006 /sys/devices/ap/card04/04.0047 @@ -146,10 +155,20 @@ If you recall from the description of an AP Queue, AP instructions include an APQN to identify the AP queue to which an AP command-request message is to be sent (NQAP and PQAP instructions), or from which a command-reply message is to be received (DQAP instruction). The validity of an APQN is defined by the matrix -calculated from the APM and AQM; it is the cross product of all assigned adapter -numbers (APM) with all assigned queue indexes (AQM). For example, if adapters 1 -and 2 and usage domains 5 and 6 are assigned to a guest, the APQNs (1,5), (1,6), -(2,5) and (2,6) will be valid for the guest. +calculated from the APM and AQM; it is the Cartesian product of all assigned +adapter numbers (APM) with all assigned queue indexes (AQM). For example, if +adapters 1 and 2 and usage domains 5 and 6 are assigned to a guest: + + + 05 06 + +---+---+ + 01 | (01,05) | (01,06) | + +---|---+ + 02 | (02,05) | (02,06) | + +---|---+ + + +APQNs (01,05), (01,06), (02,05) and (02,06) will be valid for the guest. The APQNs can provide secure key functionality - i.e., a private key is stored on the adapter card for each of its domains - so each APQN must be assigned to @@ -349,8 +368,9 @@ matrix device. number of the the usage domain is echoed to the respective attribute file. * matrix: - A read-only file for displaying the APQNs derived from the cross product - of the adapter and domain numbers assigned to the mediated matrix device. + A read-only file for displaying the APQNs derived from the Caresian + product of the adapter and domain numbers assigned to the mediated matrix + device. * assign_control_domain: * unassign_control_domain: Write-only attributes for assigning/unassigning an AP control domain @@ -438,9 +458,10 @@ guest use. Example: === Let's now provide an example to illustrate how KVM guests may be given -access to AP facilities. For this example, we will show how to configure -three guests such that executing the lszcrypt command on the guests would -look like this: +access to AP facilities. For this example, we will assume that adapters 4, 5 +and 6 and domains 4, 71 (0x47), 171 (0xab) and 255 (0xff) are assigned to the +LPAR and are online. We will show how to configure three guests such that +executing the lszcrypt command on the guests would look like this: Guest1 -- @@ -466,7 +487,7 @@ Guest2 CARD.DOMAIN TYPE MODE -- 06 CEX5A
