Page MenuHomeFreeBSD

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

Authored by erj on Jun 20 2018, 4:26 PM.
Tags
None
Referenced Files
Unknown Object (File)
Jan 16 2024, 5:37 AM
Unknown Object (File)
Jan 8 2024, 2:29 AM
Unknown Object (File)
Jan 8 2024, 2:29 AM
Unknown Object (File)
Jan 8 2024, 2:29 AM
Unknown Object (File)
Jan 8 2024, 2:29 AM
Unknown Object (File)
Jan 8 2024, 2:29 AM
Unknown Object (File)
Jan 8 2024, 2:29 AM
Unknown Object (File)
Jan 8 2024, 2:29 AM

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 - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

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 marked 2 inline comments as done.Jun 20 2018, 6:00 PM
This revision is now accepted and ready to land.Jun 20 2018, 6:05 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.

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 ?

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.

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 ?

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.

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 ?

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 ?

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. :-)

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-}

Add acronym expansions and info on qualified module check.

This revision now requires review to proceed.Jun 22 2018, 6:38 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.

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 ?

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.

I agree, the (bailed) can be removed.

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

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

  • Run manpage through textproc/igor and fix resulting issues
This revision now requires review to proceed.Aug 27 2018, 6:20 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.

  • 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)
This revision is now accepted and ready to land.Oct 2 2018, 7:24 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

  • 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)

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

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
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

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

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
This revision was automatically updated to reflect the committed changes.