Update ixl(4) and ixlv(4) man pages

[erj]

Summary

Since we made a major update to ixl, and are about to make a major update to ixlv in D16429, take this time to refresh the man pages with new information.

Suggestions on any additional information to include are welcome.

[bjk]

Some drive-by nits inline.

share/man/man4/ixl.4

157

Man page style is to start a new line when starting a new sentence.

207

Why are we adding new commented-out code?

[erj]

Address comments.

[erj]

Any additional information that should be added to the man page? Some stats descriptions? iflib sysctls? More VF usage information?

I don't really know what's useful since I don't ever need to use the driver's man page.

[pi]

Can you tell if the boards now accept foreign/unsupported SFP+ modules ? Is there a flag now for this
or does it still insist to only accept intel-branded SFP+ modules ?

[erj]

In D15927#337295, @pi wrote:

Can you tell if the boards now accept foreign/unsupported SFP+ modules ? Is there a flag now for this
or does it still insist to only accept intel-branded SFP+ modules ?

For the most part, they only accept Intel-branded modules; this is enforced by the firmware. There are some exceptions, but I can't give you a definitive list since I'm not sure what it contains.

Cards sold with an E in front of them (e.g. EXL710) don't have this check, and I think ports that are LOMs don't have it either.

[pi]

Thanks -- will that be written down somewhere in the man page ? Who is selling EXL cards, because I've never found that ? And: What is LOM ?

[erj]

In D15927#337347, @pi wrote:

Thanks -- will that be written down somewhere in the man page ? Who is selling EXL cards, because I've never found that ? And: What is LOM ?

I should add a note about the qualified optics check to the man page.

For EXL cards, I'm not sure where they're sold. I've seen a couple in Google searches, but I think those aren't retail cards, and may have an unknown source.

LOM stands for "LAN on Motherboard". If you see an X710/X722 device with the ports attached directly to the motherboard / enabled via riser card, that's a LOM. They don't have a different PCI device ID from the regular add-in cards, but they do have slightly different firmware.

[pi]

Thanks -- if Intel would sell those EXL, that would make sense 8-)

Please expand LOM to 'onboard interfaces (LAN on Motherboard, LOM)', if possible. I'm a 30-years user of ethernet, but I've never heard that abbreviation.

If an admin can see if an interface is external or LOM, by whatever magic, can you write about it in the man page ?

[pi]

Someone found that having EVDEV in the kernel config causes buildkernel to fail in if_ixl:

https://lists.freebsd.org/pipermail/freebsd-current/2018-June/069924.html

Suggestion is to add IXL_IW to the kernel config. Is that something that should be mentioned in the
man page ?

[erj]

In D15927#337633, @pi wrote:

Please expand LOM to 'onboard interfaces (LAN on Motherboard, LOM)', if possible. I'm a 30-years user of ethernet, but I've never heard that abbreviation.

I don't think it's that rare of an abbreviation, but I can add the expansion.

If an admin can see if an interface is external or LOM, by whatever magic, can you write about it in the man page ?

I looked into this yesterday, and there may not be a 100% accurate way to do this in the driver. I can add something and maybe identify exceptions.

For the buildkernel failure, you need to remove IXL_IW because the code associated with it currently doesn't compile. We don't expect it to stay this way by 12-RELEASE, so we don't have it in the man page.

[rpokala]

In D15927#338098, @erj wrote:

In D15927#337633, @pi wrote:

Please expand LOM to 'onboard interfaces (LAN on Motherboard, LOM)', if possible. I'm a 30-years user of ethernet, but I've never heard that abbreviation.

I don't think it's that rare of an abbreviation, but I can add the expansion.

FWIW, I have always and only -- until now -- seen LOM expand to Lights-Out Management (a la IPMI, Dell iDRAC, HPE iLO, etc). So yes, please include the expansion. :-)

[pi]

I've tested the patch itself, and read through the man page. I found VF, without explaination. It stands for
'virtual functions'. Would it be possible to expand it at the first occurance ?

And: I'm sorry for the change requests, but I'm starting to use more and more 10g hardware and I really
like the man page to be helpful for newbies like myself 8-}

[erj]

Add acronym expansions and info on qualified module check.

[erj]

Should I add a section about the QCU and nvmupdate utilities? They have ports, but I don't think they have manpages, so I don't know how to properly reference them.

[pi]

Yes, please add sections on how to use both tools, and reference the ports (sysutils/intel-qcu and
sysutils/intel-nvmupdate).

I've looked up 'bailed' on dict.leo.org but did not find a valid translation. What are those 'bailed' devices ?

[erj]

In D15927#338138, @pi wrote:

Yes, please add sections on how to use both tools, and reference the ports (sysutils/intel-qcu and
sysutils/intel-nvmupdate).

I've looked up 'bailed' on dict.leo.org but did not find a valid translation. What are those 'bailed' devices ?

I did a quick google on "sfp bail" and found this: https://www.finisar.com/communication-components/sfp-bail-and-latch-assembly. I assume that's what "bailed" refers to.

I don't think I've ever seen a "non-bailed" SFP adapter, so it probably isn't necessary to add to the SFP description in the man page.

[pi]

I agree, the (bailed) can be removed.

[erj]

Remove (bailed)s

[pi]

Do you still plan to provide pointers to sysutils/intel-qcu and sysutils/intel-nvmupdate or should the man page update be committed as is ?

[erj]

I'll work on adding those pointers; they're important tools for these cards.

[erj]

• Run manpage through textproc/igor and fix resulting issues

[pi]

Do you still have the pointers to sysutils/intel-qcu and sysutils/intel-nvmupdate in mind ?

[erj]

Yes -- I did this quick update because someone mentioned the textproc/igor utility in another review. It also reminded me to come back to this.

[erj]

• ixl/ixlv(4): Update both manpages.

[pi]

Looks fine.

[0mp]

Also, there are some style problems reported by mandoc -Tlint.:

mandoc: ./share_man_man4_ixl.4:93:2: WARNING: skipping paragraph macro: Pp after Ss
mandoc: ./share_man_man4_ixl.4:99:2: ERROR: missing list type, using -item: Bl
mandoc: ./share_man_man4_ixl.4:111:46: STYLE: consider using OS macro: Fx

share/man/man4/ixl.4

142

.Xr 8 sysctl

147

Shoudn't it be a Bd or Bl?

179

.Va dev.ixl.#.supported_speeds

216

Xr 8 iovctl

[erj]

• Fix style issues found by @0mp

[0mp]

Looks good to me. 😃

There's only one thing related to .Fx I mentioned in another comment.

share/man/man4/ixl.4

100

This is not really correct.

It should be

.Fx
kernel;

because otherwise kernel is interpreted as a version of FreeBSD. It's easy to miss it as it does not affect the way this piece of text is presented by default in the terminal.

However, you may see that if you use mandoc -Thtml to generate an HTML file out of this manpage you'll get:

<span class="Ux">FreeBSD kernel</span>

[erj]

Fix incorrect use of .Fx macro

[erj]

Sorry guys, ixlv(4) is getting a name change. :p

[erj]

• Change name of ixlv(4) to iavf(4) and update Makefile

[erj]

I'm going to try to get these committed, soon; I don't have any more planned changes.