uftdi.4: Makeover!
ClosedPublic
Actions

Authored by ziaee on May 30 2025, 3:51 PM.

Details

Reviewers

mhorne
carlavilla
ivy
adrian

Group Reviewers

manpages

Commits

rG7176e1e3b547: uftdi.4: Makeover!

Summary

+ tag SPDX
+ rewrite document description to one line in contemporary style
+ rewrite synopsis in vt/iwx/mtw/uart's style, adding all sysctls
+ move ioctls into an ioctl section (we should use these more)
+ add a sysctl section listing all sysctls and their defaults
+ remove list of specific 20 year old usb serial adapters from hardware
+ move list of supported controllers to the hardware section
+ add a diagnostics section showing error messages w/o explaination
(because i have never had errors using these and don't understand them)
+ explain how the driver is loaded in description, and give usage hints

MFC after: 3 days
Thanks: cperciva (devd calls devmatch at runtime)
Thanks: linimon (you dont need to be able to read everything)
Thanks: adrian (here's how you can find things in the code)

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Skipped

Unit

Tests Skipped

Build Status

Buildable 65074
Build 61957: arc lint + arc unit

Event Timeline

ziaee created this revision.May 30 2025, 3:51 PM

Herald added a subscriber: imp. · View Herald TranscriptMay 30 2025, 3:51 PM

ziaee requested review of this revision.May 30 2025, 3:51 PM

Harbormaster completed remote builds in B64551: Diff 156303.May 30 2025, 3:51 PM

ivy added inline comments.May 31 2025, 7:02 AM

share/man/man4/uftdi.4
268	i don't really see the point of listing diagnostics and not explaining what they mean. if no one knows, it would be better to not list them at all.

mhorne accepted this revision.Mon, Jun 2, 6:37 PM

mhorne added inline comments.

share/man/man4/uftdi.4
82–98	What is the organizational logic applied here? I can't exactly make sense of this version, or the old one.
268	In general agreed. I do not count DIAGNOSTICS among the required sections, and where it is added I would emphasize common/actionable error messages above an exhaustive list. As an example here (to demonstrate what I mean, I am not picking on you), "allocating USB transfers failed" appears to be a basic error handling path, where `usbd_transfer_setup()` fails due to: invalid parameters, or some kind of resource shortage. There are several pages that state something like this in their DIAGNOSTICS as "This should not happen." The statement is factual, but arguably just fluff in the page. That said, I will not block the review on this point.

This revision is now accepted and ready to land.Mon, Jun 2, 6:37 PM

Thanks @ivy and @mhorne!

share/man/man4/uftdi.4
82–98	In driver hardware I try to generally use reverse lexographic order where it corresponds to recency, so that the oldest equipment which is least common goes last, and the stuff thats most available is near the top. That way the best and most current parts are at the top. In this case, it's roughly reverse lexographic order. The first of four numbers, if exists, corresponds to available channels (one if omitted), and the letters at the end correspond correspond to generations. The FT8s (the letters correspond to generations) are last because they're decades discontinued USB1 hubs.
268	I agree on both points. I listed them in this draft because I figured someone might comment on them if they were available. I intend to leave this open a few more days in case someone has additional feedback and then remove this section upon commit.