iwlwifi: update man pages for generations, firmware. and 11n/11ac

[bz]

Summary

Put Intel's iwlwifi better in context to iwm, iwx and iwn.

Document the important tunables so users know where to go.
Document the port/package for firmware where firmware is now
maintained.
Adjust wording and table for the firmware and a flavor column.
Update History sections for 11n/11ac support as well as firmware
module removal from base.

Sponsored by: The FreeBSD Foundation
MFC after: 3 days

[ziaee]

This is awesome! Firmware table is a bit way super long, but it's maybe for the best that it's documented. Few suggestions/ideas:

share/man/man4/iwlwifi.4

1

You could also remove this dash if you want, it was for a parser Warner abandoned.

263

Are these only available in loader.conf or can they also be modified with sysctl at runtime?

263

These are loader tunable since they can't be modified at runtime

share/man/man4/iwlwififw.4

30–31

Dts are uppercase, also errors on linter

35

I really like what's in uathload(8), how do you feel about it? If it's okay, can I just do them all at once in one commit?

43–46

70–71

I'm getting `WARNING: wrong number of cells: 6 columns, 1 cells on every line in this table, but I'm not sure what's wrong with it.

70–71

This table needs 6 columns on every line to not put an error on them. There may be a better way to do this, but I'm not sure.

1558

1581

[bz]

share/man/man4/iwlwififw.4

35

uathload is a program that loads firmware from user space.
Drivers like iwlwifi are loading the firmware themselves, no extra "loader" (program) needed.

52

Hmm Two .It lines I wonder if the first one also needs adjustment then?
And I assume you mean 6 columns, 5 Ta ?

70–71

What gives these warnings? In the old days man ./foo.4 > /dev/null would just show warnings. I assume that's not the case anymore.

[bz]

Address feedback from @ziaee

[emaste]

share/man/man4/iwlwifi.4

272

In general positive-sense sysctl/tunables are preferred (although upstream or backwards compatibility may dictate otherwise).

[bz]

share/man/man4/iwlwifi.4

272

I agree. These are the original Intel driver modparams so I didn't want to change the names for FreeBSD.
I also don't like the 11n_disable vs. disable_X for all the others but it leaves us with all online comments/bug reports/documentation by not being different.

Should we add a comment that these names are matching the origial Linux driver modparams?

[emaste]

The content looks good to me (with the one inline note); I defer to @ziaee for the markup.

share/man/man4/iwlwifi.4

272

Yeah, 11n_disable vs disable_11ac is rather annoying but certainly consistency with upstream makes sense for test reports, investigations etc. I think it is worth mentioning that the inconsistent/wrong-sense names match the Linux driver parameters.

[ziaee]

share/man/man4/iwlwififw.4

35

So, this manual describes how firmware is handled by iwlwifi and not an interface of itself?

52

Yes, sorry!

70–71

You can still do that, but it doesn't show as much as invoking the compiler's linter with mandoc -Tlint /here/is/the/foo. Helpfully, nearly all the warnings have an outstanding explanation in the DIAGNOSTICS section of mandoc(1).

[bz]

share/man/man4/iwlwifi.4

272

I'll add a sentence with the next update.

share/man/man4/iwlwififw.4

35

I would go eve further and say the only purpose of this manual (still) is to describe which iwlwifi chipset needs which firmware. As I said else a while ago (I think in a different review) I can see this man page vanishing in the future once everything around the firmware move from base to ports and using fwget has settled.

70–71

Thanks a lot for the mandoc -Tlint ! I'll try to remember and use that in the future. Much appreciated.

[bz]

Add a paragraph about the naming of the tunables.

[bz]

@ziaee @emaste Do you think this is sufficiently okay to get in? I might want to merge it to 14.3 still.

[ziaee]

Sorry for the delay!

[ziaee]

share/man/man4/iwlwifi.4

1

Sorry, not the whole line, but just the dash. So it should say .\*.

[bz]

share/man/man4/iwlwifi.4

1

Fixed with the commit.