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
Details
Details
- Reviewers
carlavilla mhorne bz thj - Group Reviewers
wireless manpages - Commits
- rG27c41b28b1d7: iwx.4: Initial manual page
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- 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
| share/man/man4/Makefile | ||
|---|---|---|
| 268 | where is _iwx.4 getting set? | |
Comment Actions
Thanks emaste! I don't actually know, but I thought that's the syntax for "include this manual only if this driver is compiled".
Comment Actions
@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.4Comment Actions
Attempt to fix iwx.4 Makefile based on this appears to be only for amd64 in sys/modules/Makefile
Comment Actions
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.
Comment Actions
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 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. | |
Comment Actions
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 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 and everyone I've spoken with is in agreement on that.
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. | |
| 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. | |
| share/man/man4/iwx.4 | ||
|---|---|---|
| 99 | ||
| 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. | |
| share/man/man4/iwx.4 | ||
|---|---|---|
| 151 | The manpage for ipfw is a good example of the history and authors section:
So for this drivers, it is a matter to find major contribution, and to do proper accreditation. | |
Comment Actions
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*.
Comment Actions
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.
Comment Actions
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!
Comment Actions
As as user, I found this man page very helpful and was able to set up my iwx interface using the information presented here. I actually did not know that iwx was in the tree because I didn't see a man page for it, until I saw a link to https://people.freebsd.org/~ziaee/tmp/iwx.4.pdf
Comment Actions
Thanks all for the input. Let us proceed here. Having spoken with the interested parties, I plan to handle the follow-up change describing the driver provenance.
Approved for commit, and LGTM, with one requested change.
| share/man/man4/iwx.4 | ||
|---|---|---|
| 36–38 | This implies that this knob is a debug "level", as commonly found in other drivers. But as stated below the field is a bitmask. I do not think the line provides value. | |
| share/man/man4/iwx.4 | ||
|---|---|---|
| 36–38 | Would you feel better if instead of "1" we had the bitmask for "everything"? | |
| share/man/man4/iwx.4 | ||
|---|---|---|
| 36–38 | Sure, .Cd dev.iwx.?.debug=0xffffffff | |
Comment Actions
Yes, I already gave my approval and reviewed-by. Whatever issues remain (in the eyes of whomever) can be fixed in a follow-up.
But let's get this unblocked! >:)