Page MenuHomeFreeBSD

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

Authored by erj on Jun 20 2018, 4:26 PM.

Details

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.

Diff Detail

Repository
rS FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
bjk added a subscriber: bjk.Jun 20 2018, 4:31 PM

Some drive-by nits inline.

share/man/man4/ixl.4
157 ↗(On Diff #44159)

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

207 ↗(On Diff #44159)

Why are we adding new commented-out code?

erj updated this revision to Diff 44169.Jun 20 2018, 6:00 PM

Address comments.

erj marked 2 inline comments as done.Jun 20 2018, 6:00 PM
sbruno accepted this revision.Jun 20 2018, 6:05 PM
This revision is now accepted and ready to land.Jun 20 2018, 6:05 PM
erj edited the summary of this revision. (Show Details)Jun 20 2018, 7:47 PM
erj added a comment.Jun 20 2018, 11:06 PM

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 added a subscriber: pi.Jun 20 2018, 11:16 PM

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 added a comment.Jun 21 2018, 12:10 AM
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 added a comment.Jun 21 2018, 4:56 AM

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 added a comment.Jun 21 2018, 5:17 PM
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 added a comment.Jun 21 2018, 5:23 PM

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 added a comment.Jun 22 2018, 4:53 AM

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 added a comment.Jun 22 2018, 5:15 PM
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.

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 added a comment.Jun 22 2018, 6:16 PM

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 updated this revision to Diff 44318.Jun 22 2018, 6:38 PM

Add acronym expansions and info on qualified module check.

This revision now requires review to proceed.Jun 22 2018, 6:38 PM
erj added a comment.Jun 22 2018, 6:40 PM

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 added a comment.Jun 22 2018, 6:44 PM

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 added a comment.Jun 22 2018, 6:51 PM
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 added a comment.Jun 22 2018, 7:02 PM

I agree, the (bailed) can be removed.

erj updated this revision to Diff 44319.Jun 22 2018, 7:04 PM

Remove (bailed)s

pi accepted this revision.Jun 30 2018, 8:04 AM

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 ?

This revision is now accepted and ready to land.Jun 30 2018, 8:04 AM
erj added a comment.Jul 12 2018, 5:35 PM

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

erj updated this revision to Diff 47355.Aug 27 2018, 6:20 PM
  • Run manpage through textproc/igor and fix resulting issues
This revision now requires review to proceed.Aug 27 2018, 6:20 PM
pi added a comment.Aug 27 2018, 6:33 PM

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

erj planned changes to this revision.Aug 27 2018, 7:11 PM

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 updated this revision to Diff 48642.Oct 2 2018, 6:02 AM
  • ixl/ixlv(4): Update both manpages.
erj retitled this revision from Update ixl(4) man page to Update ixl(4) and ixlv(4) man pages.Oct 2 2018, 6:03 AM
erj edited the summary of this revision. (Show Details)
pi accepted this revision.Oct 2 2018, 7:24 AM

Looks fine.

This revision is now accepted and ready to land.Oct 2 2018, 7:24 AM
0mp added a subscriber: 0mp.Oct 2 2018, 8:28 AM

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
182 ↗(On Diff #48642)

.Xr 8 sysctl

187 ↗(On Diff #48642)

Shoudn't it be a Bd or Bl?

221 ↗(On Diff #48642)

.Va dev.ixl.#.supported_speeds

257 ↗(On Diff #48642)

Xr 8 iovctl

erj updated this revision to Diff 48649.Oct 2 2018, 3:53 PM
  • Fix style issues found by @0mp
This revision now requires review to proceed.Oct 2 2018, 3:53 PM
erj marked 4 inline comments as done.Oct 2 2018, 3:54 PM
erj edited the summary of this revision. (Show Details)
0mp accepted this revision as: 0mp.Oct 2 2018, 4:00 PM

Looks good to me. 😃

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

share/man/man4/ixl.4
111 ↗(On Diff #48649)

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>
This revision is now accepted and ready to land.Oct 2 2018, 4:00 PM
erj updated this revision to Diff 48666.Oct 2 2018, 11:37 PM

Fix incorrect use of .Fx macro

This revision now requires review to proceed.Oct 2 2018, 11:37 PM
erj marked an inline comment as done.Oct 2 2018, 11:38 PM
0mp accepted this revision as: 0mp.Oct 4 2018, 3:12 PM
This revision is now accepted and ready to land.Oct 4 2018, 3:12 PM
erj planned changes to this revision.Oct 4 2018, 10:54 PM

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

erj updated this revision to Diff 48792.Oct 5 2018, 5:23 PM
  • Change name of ixlv(4) to iavf(4) and update Makefile
erj added a comment.Oct 11 2018, 10:40 PM

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

This revision is now accepted and ready to land.Oct 11 2018, 10:46 PM
sbruno accepted this revision.Oct 11 2018, 10:47 PM
0mp accepted this revision.Oct 12 2018, 8:50 AM
This revision was automatically updated to reflect the committed changes.