docs: deprecate RTAI-kernel-only hardware drivers, fix stale manpage trap - #4513
Open
grandixximo wants to merge 4 commits into
Open
docs: deprecate RTAI-kernel-only hardware drivers, fix stale manpage trap#4513grandixximo wants to merge 4 commits into
grandixximo wants to merge 4 commits into
Conversation
GENERATED_MANPAGES depends on BUILD_SYS, so removing manpages by list leaves stale files behind on uspace trees (e.g. the kbuild-only driver manpages pluto_servo.9, pluto_step.9, pcl720.9). gen_complist.py then picks up the stale files and generates links to manpages the current build configuration cannot produce, making local doc builds diverge from CI. Everything under docs/build/man is generated (halcompile output, asciidoctor output from docs/src/man, alias pages, translations), so wipe the whole tree in both clean-manpages and genclean.
These drivers only build for RTAI kernels and have never been available in uspace builds (the only builds current users run): hal_stg, hal_motenc, hal_vti, hal_evoreg, hal_ax5214h, opto_ac5, pci_8255, pcl720, pluto_servo, pluto_step They serve ISA/PCI/parport cards from the early 2000s. The poll on the forum and emc-developers found one pci_8255 user on a legacy install (unaffected by removal from master) and Vital Systems reported no Motenc cards remaining and none known in use. Mark them deprecated in the driver docs, the component list, the opto_ac5 manpage, and the comp-embedded docs of pcl720, pluto_servo and pluto_step, and note the deprecation in the changelog. Removal is intentionally not tied to a specific release. If a user with hardware shows up, the driver can still be ported to uspace; see LinuxCNC#4505
hal_skeleton is not a hardware driver but John Kasunich's code template for writing new drivers. It only builds on kbuild (RTAI), is never loaded by any config, and the source file stays in the tree as a reference.
BsAtHome
reviewed
Sep 11, 2026
Comment on lines
+9
to
+14
| [ Luca Toniolo ] | ||
| * Deprecate the RTAI-kernel-only hardware drivers (hal_stg, hal_motenc, | ||
| hal_vti, hal_evoreg, hal_ax5214h, opto_ac5, pci_8255, pcl720, | ||
| pluto_servo, pluto_step). They are not built for uspace and will be | ||
| removed in a future release. | ||
|
|
Contributor
There was a problem hiding this comment.
This is quite a lone addition. There is a list ...very... long that should have been added here. What reasoning is behind this that it must now be added to the Debian changelog?
Contributor
Author
There was a problem hiding this comment.
Kept, because this is exactly the audience that matters for a deprecation. Users do not read driver doc pages until something breaks, but people scanning the release notes do read the changelog. A deprecation that only lives in the docs of the deprecated thing itself is invisible until it is too late. If the changelog is the wrong channel, where should release-level deprecations go?
Contributor
There was a problem hiding this comment.
but people scanning the release notes do read the changelog
Optimist?
Contributor
Author
There was a problem hiding this comment.
Just trying to be as loud as I can about the deprecation, I think is better to have it than not?
- Use admonition blocks instead of one-line WARNING paragraphs - Drop the troff .SH markup from the comp descriptions, plain text is enough and the descriptions are asciidoc now - Do not add the seven never-listed drivers to components.adoc; keep the deprecation marker only on the three existing rows (opto_ac5, pluto_servo, pluto_step)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the docs side of #4505.
The ten RTAI-kernel-only drivers (hal_stg, hal_motenc, hal_vti, hal_evoreg, hal_ax5214h, opto_ac5, pci_8255, pcl720, pluto_servo, pluto_step) have not been built on uspace since 2014. The user poll on the forum and emc-developers found zero users with the hardware: the only pci_8255 respondent turned out to use plain parport, and Vital Systems reports no Motenc cards remaining and none known in use.
Three commits:
clean-manpagesremoved manpages by$(GENERATED_MANPAGES)list, which depends on BUILD_SYS, so kbuild-only driver manpages survived forever on uspace trees. gen_complist.py then generated links for them locally that CI never produces (the discrepancy hdiethelm hit in ci: Enable fail on htmlcheck error #4471). Everything under docs/build/man is generated, so wipe the tree.Verified: full build plus htmldocs pass, all ten warnings render, stale pluto_servo.9/pcl720.9 files get wiped by clean.
If a maintainer with Pluto-P hardware shows up, the uspace port is still possible (the comp compiles on uspace today), but the FPGA firmware is unmaintainable since Jeff Epler's 2013 maintainer call found no takers.