Page MenuHomeFreeBSD

iwx.4: Initial manual page
Needs ReviewPublic

Authored by ziaee on Sun, Apr 6, 6:16 PM.
Tags
None
Referenced Files
F115726722: D49687.id153269.diff
Sun, Apr 27, 6:31 PM
Unknown Object (File)
Thu, Apr 24, 3:39 PM
Unknown Object (File)
Thu, Apr 24, 8:50 AM
Unknown Object (File)
Thu, Apr 24, 8:09 AM
Unknown Object (File)
Thu, Apr 24, 6:08 AM
Unknown Object (File)
Thu, Apr 24, 3:04 AM
Unknown Object (File)
Wed, Apr 23, 11:53 PM
Unknown Object (File)
Wed, Apr 23, 11:29 PM

Details

Reviewers
carlavilla
mhorne
bz
thj
Group Reviewers
wireless
manpages
Summary
Import manual from OpenBSD, tweaked for our 
system.

Obtained from:		  OpenBSD
Reviewed by:              bz, emaste, thj
Fixes:                   1ad0f7e91582dd (Import iwx)
Differential Revision: https://reviews.freebsd.org/D49687

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Skipped
Unit
Tests Skipped
Build Status
Buildable 63649
Build 60533: arc lint + arc unit

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
share/man/man4/Makefile
717

This needs to be in the commit message

share/man/man4/iwx.4
26
bz requested changes to this revision.Sun, Apr 6, 6:42 PM
bz added a reviewer: thj.
bz added a subscriber: bz.
bz added inline comments.
share/man/man4/Makefile
717

unrelated

share/man/man4/iwx.4
34

Is this kld_list needed? devmatch should auto-load it -- unless there are no PNP entries in the driver -- then that should be fixed in iwx(4)

133

We normally don't list the firmware files anymore.
It would also for most need two of these files: a ucode and a pnvm file.

139

Please fix this paragraph.

It really should just point people at fwget(8) which will install the wifi-firmware-iwlwifi flavored packages automatically. The above is OpenBSD language; FreeBSD does/did (beofre fgwet) ship the firmware in base.

This revision now requires changes to proceed.Sun, Apr 6, 6:42 PM
ziaee marked an inline comment as done.

+ remove unrelated sorting fix, I just wanted to fix it without churn.
+ increase document description consistency
+ explain how the driver loads automatically immediately
+ explain how the firmware is obtained in files
+ remove crypto offload mentions, the import review said that's TODO
+ mention Haiku in history
+ improve see also
+ improve background mode structure

is this kld_list needed?

Not normally, but normally nothing is needed. I attempted to explain
that better in the description, while preserving traditional synopsis
showing that how you can load it manually. If compiling a non-generic
kernel, the synopsis shows how you can compile it in, or load it with
rc.conf manually, maybe because they aren't using devmatch.

Thank you so much for helping!

emaste added inline comments.
share/man/man4/Makefile
268

where is _iwx.4 getting set?

Thanks emaste! I don't actually know, but I thought that's the syntax for "include this manual only if this driver is compiled".

@ziaee ok, look at the existing examples then, further down in this file - e.g.:

.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "i386"
_acpi_asus.4=   acpi_asus.4

Attempt to fix iwx.4 Makefile based on this appears to be only for amd64 in sys/modules/Makefile

Remove one of the newlines in description,
I decided I don't really like it.

Mention no crypto offload yet in CAVEATS.
Does this driver also not yet support other offloads?
I think it would be really good to note them here.

Intel actually calls these adapters "Intel Wi-Fi 6" series.

ziaee marked 2 inline comments as done.Mon, Apr 7, 9:50 PM
ziaee marked an inline comment as done.

Realized there should be a Pp in HARDWARE.

Add SYSCTL VARIABLES, modeled off mtw.

Correct syntax typo (missing end of list).

Thanks for writing up the page! I started, but got distracted with something else. I've added some bits which will help us align to other wifi man pages

share/man/man4/iwx.4
52

I don't think we need this sentence

"The iwx driver can be configured at runtime with ifconfig(8) or at boot with rc.conf(5)."

I think we are carrying ifconfig examples in a lot of man pages which could be centralised. maybe we should expand networking(7) to be more featurefull

57

In other man pages rather than a structured list the modes are described as a sentence, .i.e., "The rtwn driver supports station, adhoc, hostap and monitor mode operation"

99

We should reference sys/dev/iwx/if_iwx_debug.h or include the bit mask here

151

My draft has this for history:

.Sh HISTORY
.Nm
first appeared in FreeBSD 15.
.Pp
.Nm
was ported as a new driver from Linux to OpenBSD to extend the hardware
supported by OpenBSD's iwn rather than incorporating support into a larger more
complex driver.
.Pp
.Nm
was ported to FreeBSD by Future Crew LLC.
.Pp
.Nm
was imported by Tom Jones under sponsorship from the FreeBSD Foundation based
on the Future Crew source release and improved to support all the hardware
suppported by iwx in OpenBSD.

I think your history is fine, while driver doesn't use any of the Haiku code (as far as I can tell), it did come that way too.

I think it is only fair to recognize the work future crew did in the port.

I suggest:

The iwx device driver first appeared in OpenBSD 6.7, Haiku R1/beta 4 and FreeBSD 15.0.
iwx was ported to FreeBSD by Future Crew LLC and imported with expanded hardware support by Tom Jones under sponsorship from the FreeBSD Foundation

Hey Tom! It's always very anxious about the relationship when I have disagreements. Even though I'm obligated to make my case, I really appreciate your review!

share/man/man4/iwx.4
52

I don't think we need this sentence

"The iwx driver can be configured at runtime with ifconfig(8) or at boot with rc.conf(5)."

I disagree. The manual explaining how to use it is at the heart of the of what a manual is for, much more so than who sponsored the initial import! It's both complete and terse, only one sentence. I think it's more true and relevant than the ifconfig examples in other manuals that describe how to connect to WEP.

I think we are carrying ifconfig examples in a lot of man pages which could be centralised.

I and everyone I've spoken with is in agreement on that.

Maybe we should expand networking(7) to be more featureful

I'm not opposed to it, but it's a quick start guide, and quick start guides loose all value when they become a giant sprawling thing. The entire reason I wrote that is crock (as it says in mail wrapper(8)). netintro(4) or wlan(4) Examples section needs to be fixed, imho.

57

What modes does this driver support?

99

In other manuals we've preferred to not link the src or include the giant table of bitmask because it's not even remotely useful unless you know how to read the source and find it already.

151

To me: Hard no. This is the style we've been using for 50 years, and adding "first" is bloat enough. Honestly, what you're suggesting is more text than the text on how to use it, and even you want me to remove that!

The history section shows how and when it came to us; it doesn't include authors. There's even a separate standard section for that, but here's why I don't like using it, and have elected not to in everything I've written:

The only place that is reflected accurately is the commit log. It looks horrible and is a lie in the manual after 10 years. It's incomplete and cannot be maintained later respectfully.

I don't want to put my name in the authors section, the reader is not looking for that. Notice I don't put my name on anything unless required, that isn't because I'm shy. I think it makes a mess.

thj requested changes to this revision.Thu, Apr 10, 8:14 AM
thj added inline comments.
share/man/man4/iwx.4
57

iwx supports station and monitor mode operation

99

I don't see why we would document the sysctl, but not include a pointer for where to find useful information. I would do one or the other.

151

You are correct this should be in an authors section.

The commit log is unable to capture the history of this driver and I think it is unfair to ignore the contributions made by the other efforts which got us here.

The provenance of this driver is very complicated, but we can add some clarity in the man page. I think it helps users and developers to understand where something came from and who they might ask for help.

This revision now requires changes to proceed.Thu, Apr 10, 8:14 AM
ziaee marked 2 inline comments as done.

BSS mode > station mode

ziaee added subscribers: jsm, adrian.
ziaee added inline comments.
share/man/man4/iwx.4
99

We do not do that for any other wifi driver which requires a bitmask for the reasons I listed above. We almost never tell them to read the source in the manual because that is always an option they would know if they had the skillset. We just had this discussion last month. Ask @adrian and @jsm.

151

Can you add this in a later commit instead of obstructing this? I really don't like this. What about Stefan Spierling who authored it originally? What about jmc? What about all the other people who helped with it? What about me who wrote this as an unpaid volunteer? Why do I have to write that a portion of the work was sponsored by whoever when I did this work as an unpaid volunteer? We almost never do this, and I think it is always unhelpful. You did already put this information in the commit log and in the copyright of the driver. In the ~300 commits to manuals I've done, I did not add authors in any of them because it's very ugly and no one likes it. It's not fair to everyone who's name isn't there.

ziaee marked an inline comment as done.
ziaee edited the summary of this revision. (Show Details)
ziaee edited the summary of this revision. (Show Details)
ziaee edited the summary of this revision. (Show Details)

Add "package" to firmware explanation, thanks @patmaddox

monwarez_mailoo.org added inline comments.
share/man/man4/iwx.4
151

The manpage for ipfw is a good example of the history and authors section:

HISTORY

The ipfw utility first appeared in FreeBSD 2.0.  dummynet was introduced
in FreeBSD 2.2.8.  Stateful extensions were introduced in FreeBSD 4.0.
ipfw2 was introduced in Summer 2002.

AUTHORS

Ugen J. S. Antsilevich,
Poul-Henning Kamp,
Alex Nash,
Archie Cobbs,
Luigi Rizzo,
Rasool Al-Saadi.

API based upon code written by Daniel Boulet for BSDI.

Dummynet has been introduced by Luigi Rizzo in 1997-1998.

Some early work (1999-2000) on the dummynet traffic shaper supported by
Akamba Corp.

The ipfw core (ipfw2) has been completely redesigned and reimplemented by
Luigi Rizzo in summer 2002.  Further actions and options have been added
by various developers over the years.

In-kernel NAT support written by Paolo Pisati <piso@FreeBSD.org> as part
of a Summer of Code 2005 project.

SCTP nat support has been developed by The Centre for Advanced Internet
Architectures (CAIA) ⟨http://www.caia.swin.edu.au⟩.  The primary
developers and maintainers are David Hayes and Jason But.  For further
information visit: ⟨http://www.caia.swin.edu.au/urp/SONATA⟩

Delay profiles have been developed by Alessandro Cerri and Luigi Rizzo,
supported by the European Commission within Projects Onelab and Onelab2.

CoDel, PIE, FQ-CoDel and FQ-PIE AQM for Dummynet have been implemented by
The Centre for Advanced Internet Architectures (CAIA) in 2016, supported
by The Comcast Innovation Fund.  The primary developer is Rasool Al-
Saadi.

So for this drivers, it is a matter to find major contribution, and to do proper accreditation.

Thank you, this is a perfect example for what I am trying to say.

At just the last five years; ae@, markj@, Damjan Jovanovic, igoro@, eugen@, dougm@, Lexi Winter, gbe@, Ben Wilber, imp@, Elyes Haouas, glebius@, Karim Fodil-lemelin, kp@, rscheff@, zlei@, jhb@, melifaro@, Boris lytochkin, ceri@, jlduran@, jhibbits@, Goran Mekic, rscheff@, tuxen@, dim@, cy@, Arseny Smalyuk, Reid Linnemann, mjg@, loos@, donner@, karels@, nc@, Evgeniy Khramtsov, arichardson@, jtl@, emaste@, fernape@, adrian@, rgrimes@, bdrewery@, hselasky@, thj@, kevans@, luporl@, and ygy@ have been known to have worked on ipfw.

Many of these people have dozens of commits to ipfw doing major work or critical maintenance. It would be madness to list them all, and it is unfair not to represent them. However they are represented in the commit log.

Additionally several companies have some major sponsorship in the last 5 years to ipfw, most notably and consistently are Yandex and Netgate, again, I got this just now from the commit log, where it cannonically belongs.

However, I would like to point out that those companies do not *advertise* in the *reference manual*.

Even further, the links to the organizations listed in ipfw are dead.

ok this is blocked for a lot of bike shed reasons.

I suggest the following:

HISTORY:

  • (paraphrased, use what we normally do): This driver appeared in FreeBSD-15.0.

eg, ath(4) just says the driver first appeared in freebsd-5.2. First or no first, that's up to you.

Then, land what we have, so there's a manpage.

Then, let's open up a separate review to go nail down what to do with the AUTHORS section to try and properly capture the source(s) of this driver.

Thank you for suggesting a compromise!

I too would like to get this in the tree for our testers and iron out
history and authors later!