sdhci.4: Improve HARDWARE
ClosedPublic
Actions

Authored by ziaee on Oct 2 2025, 3:34 PM.

Details

Reviewers

imp
ivy
olce

Commits

rG3b7da838aa8f: sdhci.4: Improve HARDWARE for HW Relnotes + SPDX
rGbc433a0b7b04: sdhci.4: Improve HARDWARE for HW Relnotes + SPDX

Summary

Move BUGS to HARWARE, removing the old list that was previously there, and cleaning it up a bit and adding mention of those
built into Intel chipsets.

MFC after: 1 hr
Discussed with: imp, ivy, olce

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

ziaee requested review of this revision.Oct 2 2025, 3:34 PM

ziaee created this revision.

Harbormaster completed remote builds in B67491: Diff 163351.Oct 2 2025, 3:34 PM

ziaee edited the summary of this revision. (Show Details)Oct 2 2025, 3:39 PM

olce added inline comments.Oct 2 2025, 3:48 PM

share/man/man4/sdhci.4
59–83	It seems unfortunate to repeat information from the DESCRIPTION section, but I guess this is for the sake of HARWARE-to-rel-notes machinery? Isn't this machinery just supposed to import the support hardware list from HARDWARE? In other words, isn't some preamble/intro already present in the rel notes? Even if it's not for now, I'm wondering if we shouldn't also include the text under DESCRIPTION in the release notes.
73–77	Wrapping is pretty tight here. You should allow up to 80 columns per line as in code. I don't see `mdoc(7)` or some other manual page specifying that, but too short lines slightly impair quick reading.

ziaee added inline comments.Oct 2 2025, 8:33 PM

share/man/man4/sdhci.4
59–83	It imports the entire section. Please, take a look. https://www.freebsd.org/releases/15.0R/hardware/

Looking at the hardware driver suggests this page is even more out of date than I thought.
I don't have time to enumerate everything here.

But we support a number of these devices in the embedded space, and that's where the crazy is at its highest.

share/man/man4/sdhci.4
71–83	The .Nm driver supports the SD Host Controller Specification. When attaching via the PCI bus, the controller is automatically configured. Many SoC chips provide a SDHCI controller directly mapped to I/O memory. For those, the controller may be configured using the FDT or ACPI methods, supplied by your board's vendor.
73–77	I'd replace this with: Unlike most other drivers that support a generic standard, .Nm requires a large number of quirks to cope with hardware bugs, proprietary registers and poorly specified power management. While many chipsets from Intel, Xilinx, Rockchip, Freescale, Ricoh, and TI have these entries, suboptimal performance may result when using some controllers. Quirks and custom configuration are most often required when the device is configured via FDT or ACPI.