safexel manuals: Improve apropos and HW relnotes

[ziaee]

Summary

safe.4:
Improve document description (Nd) for apropos. Remove Nm from sysctls
in synopsis. This was causing this page to get pulled into results for
`apropos sysctl`. Instead, use kernel declaration macros like vt(4).
Convert the HARDWARE tagged list to a column list for better rendering
in HW Relnotes. Tested in man(1) at MANWIDTH 59 and 80.

safexcel.4:
Nd: s/security packet/cryptographic offload/ for apropos.
HARDWARE: Create this section for inclusion in the HW relnotes.

SPDX:           both tagged
MFC after:      3 days
MFC to:         13.5
Reported by:    markj (cryptographic offload, Inside Secure)
Reviewed by:    jhb, markj, mhorne

[ziaee]

Sorry, I had a stray capitalized letter

[ziaee]

Turns out, actually if the column specification is the way
that the begin list macro wants, the lines can be folded
however, so... fold them better in the src.

Tested on MANWIDTH 59 and 80

[ziaee]

+ add crypto to safexcel document description for apropos
+ attempt to improve commit message

[markj]

share/man/man4/safexcel.4

32

78

This effectively duplicates the wording from the DESCRIPTION section. How exactly does this section get used?

[ziaee]

The hardware section appears verbatim in the HW relnotes:
https://www.freebsd.org/releases/14.2R/hardware/

[mhorne]

LGTM

[ziaee]

I am interested in waiting for Mark's feedback upon the HARDWARE section. Better would be to list which devices are supported, if anyone knows anything.

Also, as for his comment to s/security packet/cryptographic offload/, I think those are much more specific/appropriate search keywords, can we do that consistently? There's also hifn(4) https://man.freebsd.org/cgi/man.cgi?query=hifn&apropos=0&sektion=0&manpath=FreeBSD+14.1-RELEASE+and+Ports&arch=default&format=html and ccr(4) https://man.freebsd.org/cgi/man.cgi?query=ccr&apropos=0&sektion=0&manpath=FreeBSD+14.1-RELEASE+and+Ports&arch=default&format=html

Adding jhb for that discussion.

[jhb]

share/man/man4/safe.4

124

Rewrapping the existing text here seems gratuitous?

[jhb]

safe(4) and hifi(4) are mostly obsolete and the kernel no longer supports many of these algorithms (DES, 3DES, MD-5) for IPsec or other crypto(9) consumers. In terms of manpage language, "crypto accelerator" seems to be the common pattern in .Nd descriptions and is what I used in ccr(4). I don't have any strong opinions, though "security packet engine" seems a bit more obtuse. The typical language I see is something like "crypto co-processor" or "crypto accelerator". Mark's suggestion of "offload engine" is also better than "packet engine". OpenSSL has in the past used the term "engine" for accelerators/co-processors though I think those are now supposed to be custom providers in modern OpenSSL jargon rather than engines.

[markj]

In D47706#1088743, @jhb wrote:

safe(4) and hifi(4) are mostly obsolete and the kernel no longer supports many of these algorithms (DES, 3DES, MD-5) for IPsec or other crypto(9) consumers. In terms of manpage language, "crypto accelerator" seems to be the common pattern in .Nd descriptions and is what I used in ccr(4). I don't have any strong opinions, though "security packet engine" seems a bit more obtuse. The typical language I see is something like "crypto co-processor" or "crypto accelerator". Mark's suggestion of "offload engine" is also better than "packet engine". OpenSSL has in the past used the term "engine" for accelerators/co-processors though I think those are now supposed to be custom providers in modern OpenSSL jargon rather than engines.

"Security packet engine" is the terminology from the datasheets I used to write the driver. The device has a lot of functionality to support offloading of IPSec, TLS, various wifi protocols, ...

share/man/man4/safexcel.4

77

[ziaee]

While testing, I discovered the Nm's in SYNOPSIS were causing this page to get pulled into results for apropos sysctl. I rewrote it the way it's written in vt(4).

I do not know if it is accurate though that the sysctls can be either loader.conf or sysctl.conf.

add Sponsored trailer because I'm doing this at work.

Wrap some text back the way it was.

[ziaee]

Humble ping?

[markj]

If you mail me git format-patch output or submit it on github, I'll apply it.

In D47706#1091415, @concussious.bugzilla_runbox.com wrote:

While testing, I discovered the Nm's in SYNOPSIS were causing this page to get pulled into results for apropos sysctl. I rewrote it the way it's written in vt(4).

I do not know if it is accurate though that the sysctls can be either loader.conf or sysctl.conf.

Looking at the definitions in safe.c, they can only be set in sysctl.conf, so this part should be corrected.

add Sponsored trailer because I'm doing this at work.

Wrap some text back the way it was.

[ziaee]

Sorry I slipped on this one. May I do the synopsis in the style of https://reviews.freebsd.org/D48905, which is like vt(4)?