Bug 252984

Summary:	qat(4): minor flaws
Product:	Documentation	Reporter:	Walter von Entferndt <walter.von.entferndt>
Component:	Manual Pages	Assignee:	Mark Johnston <markj>
Status:	Closed FIXED
Severity:	Affects Many People	CC:	doc, strongswan
Priority:	---
Version:	Latest
Hardware:	amd64
OS:	Any

Description Walter von Entferndt 2021-01-24 23:21:45 UTC

FYI the man page qat(4) misses to list some QAT-enabled CPUs/SoCs, e.g. some models of Xeon D-21xx also support it; I'm not sure about newer gen. 11 & later Xeons.

2nd, IMHO the term "chipset" is inartfully expressed here, since these Xeon D are SoC including a QAT logic circuit; from my limited understanding, this has nothing to do with the chipset, but the QAT "device" is an independent logic circuit that either is added (& enabled) on the die or not.

I would like to kindly suggest not to list all CPUs & SoCs that support QAT, since this is a moving target.  Instead, a wording like "...on all systems that supprt QAT or have an external QAT device (add-on card).".  Additionally, it is helpful to include a hint how to get that information, like this: "Systems supporting QAT include the term QAT in their CPU features.  It can be checked e.g.
On the command line or shell script: grep -E 'Features.+QAT' /var/run/dmesg.boot
In a program with the C-library function [...]".

A note on the 1st command: IIRC the system messages are stored in a circular buffer, so the CPU features fetched at boot time might have been scrolled out off the buffer when using the dmesg(8) utility.

I'm not a native english speaker, thus I do not send a patch but leave it up to you to find a good wording.

Regards

Comment 1 Conrad Meyer freebsd_committer

2021-01-25 14:21:01 UTC

It's sort of important to define which hardware models our driver supports, because it isn't all of them.  I think there are historical devices called QAT with a different programming model that we do not support.  (Maybe I'm mistaken; I'm sure Mark is more familiar.)

From the OS perspective, qat is a generic PCIe device.  Sometimes it is part of a SoC, but I believe Intel has also produced installable PCIe board versions.  (I don't know if our driver supports those models or not.)  I don't think it is enumerated in CPU feature flags (dmesg), even on SoC models.

Leaving it to Mark but IMO this is NOTABUG.

Comment 2 Walter von Entferndt 2021-01-25 14:58:35 UTC

(In reply to Conrad Meyer from comment #1)
> I think there are historical devices called QAT with a different programming
> model that we do not support.
>
Then I would like to propose s/th like "This driver supports only versions > x.y (newer than Sep 2020)."  Maybe in the NOTES or BUGS section of the man page?

> I believe Intel has also produced installable PCIe board versions.
>
Yes, I've read that on the Intel website, too.

> Leaving it to Mark but IMO this is NOTABUG.
>
Agreed, that's why I wrote "minor flaws".  Is there a better way to communicate change requests to the docs?  Should I have been using the mailing list instead?

Comment 3 Mark Johnston freebsd_committer

2021-01-27 17:03:17 UTC

I basically listed the devices that I have tested.  Perhaps a caveat to that effect would be good enough.  I agree that trying to maintain a comprehensive list is probably futile, but if we qualify the existing list with a comment to the effect that other platforms may be supported, I think that's better than not providing anything.

QAT always appears as a PCIe device, it's not reported in the CPU feature flags.  dmesg won't help you unless the driver is loaded.  Our driver supports some add-on devices.

Comment 4 commit-hook freebsd_committer

2021-01-27 20:32:55 UTC

A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=e1b50e8184fca00520774d43bd7bdd0ccbe9a1d2

commit e1b50e8184fca00520774d43bd7bdd0ccbe9a1d2
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2021-01-27 20:31:10 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2021-01-27 20:31:10 +0000

    qat.4: Minor tweaks

    - Document a constraint on the AAD size for AES-GCM.
    - Note that the list of supported platforms and add-on devices is not
      complete and indicate that QAT devices will show up in pciconf
      output. [1]

    PR:             252984 [1]
    MFC after:      3 days
    Sponsored by:   Rubicon Communications, LLC ("Netgate")

 share/man/man4/qat.4 | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

Comment 5 commit-hook freebsd_committer

2021-01-30 00:40:03 UTC

A commit in branch stable/13 references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=a455b23cf348885491f83c6a4734bb6fddf0d481

commit a455b23cf348885491f83c6a4734bb6fddf0d481
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2021-01-27 20:31:10 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2021-01-30 00:39:15 +0000

    qat.4: Minor tweaks

    - Document a constraint on the AAD size for AES-GCM.
    - Note that the list of supported platforms and add-on devices is not
      complete and indicate that QAT devices will show up in pciconf
      output. [1]

    PR:             252984 [1]
    Sponsored by:   Rubicon Communications, LLC ("Netgate")

    (cherry picked from commit e1b50e8184fca00520774d43bd7bdd0ccbe9a1d2)

 share/man/man4/qat.4 | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

Comment 6 Francois ten Krooden 2021-03-03 08:10:41 UTC

I also noticed that the section to load the qat driver from loader.conf contains two errors for the kernel drivers.

qat_c63xfw_load="YES"
qat_dh895xcc_load="YES"

should be

qat_c62xfw_load="YES"
qat_dh895xccfw_load="YES"

Comment 7 commit-hook freebsd_committer

2021-03-03 14:09:30 UTC

A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=3adf72a36b9b151eef57e3d83f71a3a9fbacb78d

commit 3adf72a36b9b151eef57e3d83f71a3a9fbacb78d
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2021-03-03 14:07:53 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2021-03-03 14:07:53 +0000

    qat.4: Fix some firmware module names

    PR:             252984
    MFC after:      1 week

 share/man/man4/qat.4 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Comment 8 Mark Johnston freebsd_committer

2021-03-03 14:10:23 UTC

(In reply to strongswan from comment #6)
Thanks, fixed.

Comment 9 commit-hook freebsd_committer

2021-03-11 15:50:47 UTC

A commit in branch stable/13 references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=e8ff5725e63d63e0473f3a394bc466a0a97222c7

commit e8ff5725e63d63e0473f3a394bc466a0a97222c7
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2021-03-03 14:07:53 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2021-03-11 15:50:26 +0000

    qat.4: Fix some firmware module names

    PR:             252984

    (cherry picked from commit 3adf72a36b9b151eef57e3d83f71a3a9fbacb78d)

 share/man/man4/qat.4 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Comment 10 commit-hook freebsd_committer

2021-03-11 15:51:48 UTC

A commit in branch stable/12 references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=623fe87b217685dea455a1740435d2a09aa11151

commit 623fe87b217685dea455a1740435d2a09aa11151
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2021-03-03 14:07:53 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2021-03-11 15:50:51 +0000

    qat.4: Fix some firmware module names

    PR:             252984

    (cherry picked from commit 3adf72a36b9b151eef57e3d83f71a3a9fbacb78d)

 share/man/man4/qat.4 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)